List

View in Lexicon

Lists are a visual representation of a dataset, based on groups of related content, that is organized vertically.

installyarn add @clayui/list
versionNPM Version
useimport List from '@clayui/list';

Table of Contents

A list can composable by a Header, an Item and Quick Actions.

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import List from '@clayui/list';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<List>
					<List.Header>This is a header</List.Header>
					<List.Item flex>
						<List.ItemField>Item 1</List.ItemField>

						<List.ItemField>ItemField</List.ItemField>

						<List.ItemField expand>
							<List.ItemTitle>
								Item Title and expanded
							</List.ItemTitle>
							<List.ItemText>Item Text</List.ItemText>
						</List.ItemField>

						<List.ItemField>ItemField</List.ItemField>
					</List.Item>

					<List.Item flex>
						<List.ItemField>Item 2</List.ItemField>
						<List.ItemField expand>
							<List.ItemTitle>
								Item Title and expanded
							</List.ItemTitle>
							<List.ItemText>
								Hover this item for action menu
							</List.ItemText>
						</List.ItemField>
						<List.ItemField>
							<List.QuickActionMenu>
								<List.QuickActionMenu.Item
									aria-label="Delete"
									title="Delete"
									onClick={() => alert('Clicked the trash!')}
									symbol="trash"
								/>

								<List.QuickActionMenu.Item
									aria-label="Settings"
									title="Settings"
									onClick={() => alert('Clicked the cog!')}
									symbol="cog"
								/>
							</List.QuickActionMenu>
						</List.ItemField>
					</List.Item>

					<List.Header>This is another header</List.Header>
					<List.Item flex>
						<List.ItemField>Item 3</List.ItemField>

						<List.ItemField>ItemField</List.ItemField>
					</List.Item>
				</List>
			</div>
		</Provider>
	);
}

QuickActionMenu

Use QuickActionMenu composition inside Item for defining a QuickActionMenu.

Wrap QuickActionMenu.Item inside QuickActionMenu for defining an Item of QuickActionMenu. See the following example:

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import List from '@clayui/list';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<List showQuickActionsOnHover>
					<List.Item flex>
						<List.ItemField expand>
							<List.ItemTitle>Item 1</List.ItemTitle>
							<List.ItemText>
								Hover this item for quick action menu
							</List.ItemText>
						</List.ItemField>
						<List.ItemField>
							<List.QuickActionMenu>
								<List.QuickActionMenu.Item
									aria-label="Delete"
									title="Delete"
									onClick={() => alert('Clicked the trash!')}
									symbol="trash"
								/>
								<List.QuickActionMenu.Item
									aria-label="Settings"
									title="Settings"
									onClick={() => alert('Clicked the cog!')}
									symbol="cog"
								/>
							</List.QuickActionMenu>
						</List.ItemField>
					</List.Item>
				</List>
			</div>
		</Provider>
	);
}

List children

To ensure your html structure is accessible, make sure any children passed to List are li elements. Both List.Item and ClayListHeader are li elements.

API Reference

List

typeof List
Parameters

children

React.ReactElement<React.HTMLAttributes<HTMLLIElement>, string | React.JSXElementConstructor<any>> | Array<React.ReactElement<React.HTMLAttributes<HTMLLIElement>, string | React.JSXElementConstructor<any>>> | undefined

showQuickActionsOnHover

boolean | undefined
Returns
Element

Item

React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLLIElement>>
Parameters

action

boolean | undefined

Flag to indicate if the list-group-item-action class should be applied.

active

boolean | undefined

Flag to indicate if item is active or selected.

disabled

boolean | undefined

Flag to indicate if item should be displayed with a disabled style.

flex

boolean | undefined

Flag to indicate if item should be display: flex.

header

boolean | undefined

Flag to indicate if item is used as a header.

Returns
ReactElement<any, string | JSXElementConstructor<any>> | null

ItemText

React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLParagraphElement>>
Parameters

subtext

boolean | undefined

Flag to indicate if content should be styled as subtext.

Returns
ReactElement<any, string | JSXElementConstructor<any>> | null

ItemTitle

React.ForwardRefExoticComponent<React.BaseHTMLAttributes<HTMLAnchorElement> & React.RefAttributes<HTMLDivElement>>
React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLLIElement> & React.RefAttributes<HTMLLIElement>>

ListWithItems

({ className, itemIdentifier, items, selectedItemsMap, onSelectedItemsChange, spritemap, ...otherProps }: IProps) => JSX.Element
Parameters
Properties

itemIdentifier

string | undefined= "id"

Property of item that makes it unique from other items. Defaults to 'id'.

items

Array<IListItem>= []

Items to show in list.

onSelectedItemsChange

((map: IBooleanMap) => void) | undefined

Callback for when selected items change.

selectedItemsMap

IBooleanMap | undefined= {}

Map of items that are currently selected.

spritemap

string | undefined

Path to spritemap for icon symbol.

Returns
Element

QuickActionMenu

IForwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>
Edit this page on GitHub

Contributors

Matuzalém Teles, Bryce Osterhaus, Diego Nascimento, Krešimir Čoko, victorvalle, Patrick Yeo

Last edited May 9, 2025 at 6:15:38 AM

Table of Contents