List

yarn add @clayui/list

Stable3.0.5

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

Take a look at our Storybook for more information about this component.
Check the Lexicon Lists Pattern for a more in-depth look at the motivations and proper usage of this component.

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

  • This is a header

  • Item 1
    ItemField

    Item Title and expanded

    Item Text

    ItemField
  • Item 2

    Item Title and expanded

    Hover this item for action menu

  • This is another header

  • Item 3
    ItemField

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:

  • Item 1

    Hover this item for quick action menu

API

ClayList

PropertyTypeRequiredDefaultDescription
showQuickActionsOnHover
booleantrueFlag to indicate if action items should be shown on hover. Defaults to `true`

ClayList.Header

Extends from React.HTMLAttributes<HTMLLIElement>

ClayList.Item

PropertyTypeRequiredDefaultDescription
action
booleanfalseFlag to indicate if the `list-group-item-action` class should be applied.
active
booleanfalseFlag to indicate if item is active or selected.
disabled
booleanfalseFlag to indicate if item should be displayed with a disabled style.
flex
booleanfalseFlag to indicate if item should be `display: flex`.
header
booleanfalseFlag to indicate if item is used as a header.

ClayList.ItemField

PropertyTypeRequiredDefaultDescription
expand
booleanFlag to indicate if field should automatically expand its width to fit in the containing space.

ClayList.ItemText

PropertyTypeRequiredDefaultDescription
subtext
booleanFlag to indicate if content should be styled as subtext.

ClayList.ItemTitle

Extends from React.HTMLAttributes<HTMLHeadingElement>

ClayList.QuickActionMenu

Extends from React.HTMLAttributes<HTMLDivElement>

ClayList.QuickActionMenu.Item

PropertyTypeRequiredDefaultDescription
href
stringValue of path the item should link to.
spritemap
stringPath to icon spritemap.
symbol
stringtrueName of icon symbol

ClayListWithItems

PropertyTypeRequiredDefaultDescription
itemIdentifier
string | 'id''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) => voidCallback for when selected items change.
selectedItemsMap
IBooleanMap{}Map of items that are currently selected.
spritemap
stringPath to spritemap for icon symbol.

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

Check the Lexicon List Pattern for a more in-depth look at the motivations and proper usage of this component.

List sections help separate content by a specific category or type.

Example

Align content inside a .list-group-item element with a flexbox with .list-group-item-flex.

Use a combination of .flex-col and .flex-col.flex-col-expand to control the size of each cell.

Add the class show-dropdown-action-on-active to display dropdown-menus when active in List Groups.

Direct descendants of flex-col become block level elements by default. See https://www.w3.org/TR/css-flexbox-1/#flex-items. If you want to display content using floats, inline, or inline-block, wrap the content with a block level element such as a div. 
<ul class="list-group show-quick-actions-on-hover">
	<li class="list-group-header">
		<h3 class="list-group-header-title">List Section</h3>
	</li>
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<p class="list-group-title text-truncate">
				<a href="#1">Account Example One</a>
			</p>
			<p class="list-group-subtitle text-truncate">Second Level Text</p>
			<div class="list-group-detail">
				<span class="label label-success">
					<span class="label-item label-item-expand">Approved</span>
				</span>
			</div>
		</div>
		<div class="autofit-col">
			<div class="quick-action-menu">
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
			</div>
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
	<li class="list-group-item list-group-item-flex active">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input
						checked
						class="custom-control-input"
						type="checkbox"
					/>
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<p class="list-group-title">
				<a href="#1">Account Example One</a>
			</p>
			<p class="list-group-subtitle">Second Level Text</p>
			<div class="list-group-detail">
				<span class="label label-success">
					<span class="label-item label-item-expand">Approved</span>
				</span>
			</div>
		</div>
		<div class="autofit-col">
			<div class="quick-action-menu">
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
			</div>
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
</ul>

More examples can be found in dataset template.

Variations

Bordered

Use .list-group-bordered on .list-group to style .list-group-item-flex like a table.

<ul class="list-group list-group-bordered">
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<section class="autofit-section">
				<div class="list-group-title">
					<span class="text-truncate-inline">
						<a class="text-truncate" href="#1"
							>Text Truncate Example</a
						>
					</span>
				</div>
				<p class="list-group-subtitle">.list-group-subtitle</p>
				<p class="list-group-subtitle">
					<a href="#1">.list-group-subtitle a</a>
				</p>
				<p class="list-group-text">
					This is an example of .list-group-text and a
					<a href="#1">link</a>.
				</p>
				<p class="list-group-text">
					<a class="list-group-text-link" href="#1"
						>a.list-group-text-link</a
					>
				</p>
				<p class="list-group-text">
					<span class="text-truncate-inline">
						<a class="list-group-text-link text-truncate" href="#1"
							>Truncated a.list-group-text-link</a
						>
						and another <a href="#1">link</a>
					</span>
				</p>
				<p class="list-group-subtext">
					This is .list-group-subtext and a <a href="#1">link</a>.
				</p>
				<p class="list-group-subtext">
					<a class="list-group-subtext-link" href="#1"
						>Regular a.list-group-subtext-link</a
					>
				</p>
				<p class="list-group-subtext">
					<span class="text-truncate-inline">
						<a
							class="list-group-subtext-link text-truncate"
							href="#1"
							>Truncated a.list-group-subtext-link</a
						>
						and another <a href="#1">link</a>
					</span>
				</p>
				<div class="list-group-detail">
					<span class="label label-warning">
						<span class="label-item label-item-expand"
							>Pending</span
						>
					</span>
				</div>
			</section>
		</div>
		<div class="autofit-col">
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<section class="autofit-section">
				<div class="list-group-title">
					<a href="#1">Account Example Two</a>
				</div>
				<p class="list-group-subtext">List Group Subtext</p>
				<div class="list-group-detail">
					<span class="label label-info">
						<span class="label-item label-item-expand">Info</span>
					</span>
				</div>
			</section>
		</div>
		<div class="autofit-col">
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
</ul>

Default

<ul class="list-group">
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-indicator"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				...
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<p class="list-group-title text-truncate">
				<a href="#1">Account Example One</a>
			</p>
			<p class="list-group-subtitle text-truncate">Second Level Text</p>
		</div>
		<div class="autofit-col">
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
</ul>

Notification

<ul class="list-group list-group-notification">
	<li class="list-group-item list-group-item-flex list-group-item-primary">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				...
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<section class="autofit-section">
				<div class="list-group-title">
					<a href="#1">Account Example One</a>
				</div>
				<p class="list-group-subtext">List Group Subtext</p>
			</section>
		</div>
		<div class="autofit-col">
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<section class="autofit-section">
				<div class="list-group-title">
					<a href="#1">Account Example Two</a>
				</div>
				<p class="list-group-subtext">List Group Subtext</p>
			</section>
		</div>
		<div class="autofit-col">
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
</ul>

Group Elements

Use the .list-group-header and .list-group-header-title class.

<ul class="list-group">
	<li class="list-group-header">
		<h3 class="list-group-header-title">List Group Header</h3>
	</li>
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<section class="autofit-section">
				<div class="list-group-title">
					<span class="text-truncate-inline">
						<a class="text-truncate" href="#1"
							>ReallySuperInsanelyJustIncrediblyLongAndTotallyNotPossibleWordButWeAreReallyTryingToCoverAllOurBasesHereJustInCaseSomeoneIsNutsAsPerUsual</a
						>
					</span>
				</div>
				<p class="list-group-subtext">
					<span class="text-truncate-inline">
						<span class="text-truncate">List Group Subtext</span>
					</span>
				</p>
				<div class="list-group-detail">
					<span class="label label-success">
						<span class="label-item label-item-expand"
							>Approved</span
						>
					</span>
				</div>
			</section>
		</div>
		<div class="autofit-col">
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
</ul>

Items

Colors

  • List Item Normal
  • List Item Success
  • List Item Info
  • List Item Warning
  • List Item Danger
  • List Item Light
  • List Item Dark
<ul class="list-group">
	<li class="list-group-item">List Item Normal</li>
	<li class="list-group-item list-group-item-success">List Item Success</li>
	<li class="list-group-item list-group-item-info">List Item Info</li>
	<li class="list-group-item list-group-item-warning">List Item Warning</li>
	<li class="list-group-item list-group-item-danger">List Item Danger</li>
	<li class="list-group-item list-group-item-light">List Item Light</li>
	<li class="list-group-item list-group-item-dark">List Item Dark</li>
</ul>

Active Colors

List Item Action Normal Active List Item Action Success Active List Item Action Info Active List Item Action Warning Active List Item Action Danger Active List Item Action Light Active List Item Action Dark Active 
<div class="list-group">
	<a class="active list-group-item list-group-item-action" href="#1"
		>List Item Action Normal Active</a
	>
	<a
		class="active list-group-item list-group-item-action list-group-item-success"
		href="#1"
		>List Item Action Success Active</a
	>
	<a
		class="active list-group-item list-group-item-action list-group-item-info"
		href="#1"
		>List Item Action Info Active</a
	>
	<a
		class="active list-group-item list-group-item-action list-group-item-warning"
		href="#1"
		>List Item Action Warning Active</a
	>
	<a
		class="active list-group-item list-group-item-action list-group-item-danger"
		href="#1"
		>List Item Action Danger Active</a
	>
	<a
		class="active list-group-item list-group-item-action list-group-item-light"
		href="#1"
		>List Item Action Light Active</a
	>
	<a
		class="active list-group-item list-group-item-action list-group-item-dark"
		href="#1"
		>List Item Action Dark Active</a
	>
</div>
List Item 1 List Item 2 List Item 4 
<div class="list-group">
	<a class="list-group-item list-group-item-action" href="#1">List Item 1</a>
	<a class="list-group-item list-group-item-action" href="#1">List Item 2</a>
	<button class="list-group-item list-group-item-action" type="button">
		List Item 3
	</button>
	<a class="list-group-item list-group-item-action" href="#1">List Item 4</a>
</div>

Actions on Hover

Anchors
<ul class="list-group show-quick-actions-on-hover">
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<section class="autofit-section">
				<div class="list-group-title">
					<a href="#1">Anchors</a>
				</div>
			</section>
		</div>
		<div class="autofit-col">
			<div class="quick-action-menu">
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
				<a
					class="component-action quick-action-item"
					href="#1"
					role="button"
				>
					...
				</a>
			</div>
			<div class="dropdown dropdown-action">
				<a
					aria-expanded="false"
					aria-haspopup="true"
					class="component-action dropdown-toggle"
					data-toggle="dropdown"
					href="#1"
					id="dropdownAction1"
					role="button"
				>
					...
				</a>
				<ul
					aria-labelledby=""
					class="dropdown-menu dropdown-menu-right"
				>
					<li>
						<a class="dropdown-item" href="#1" role="button"
							>Remove</a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1" role="button"
							>Download</a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1" role="button"
							>Checkout</a
						>
					</li>
				</ul>
			</div>
		</div>
	</li>
</ul>
Buttons
<ul class="list-group show-quick-actions-on-hover">
	<li class="list-group-item list-group-item-flex">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input class="custom-control-input" type="checkbox" />
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<section class="autofit-section">
				<div class="list-group-title">
					<span class="text-truncate-inline">
						<a class="text-truncate" href="#1"
							>Account Example One</a
						>
					</span>
				</div>
				<p class="list-group-subtext">
					<span class="text-truncate-inline">
						<span class="text-truncate">List Group Subtext</span>
					</span>
				</p>
			</section>
		</div>
		<div class="autofit-col">
			<div class="quick-action-menu">
				<button
					class="component-action quick-action-item"
					type="button"
				>
					...
				</button>
				<button
					class="component-action quick-action-item"
					type="button"
				>
					...
				</button>
				<button
					class="component-action quick-action-item"
					type="button"
				>
					...
				</button>
			</div>
			<div class="dropdown dropdown-action">
				<button
					aria-expanded="false"
					aria-haspopup="true"
					class="component-action dropdown-toggle"
					data-toggle="dropdown"
					id="dropdownAction1"
					type="button"
				>
					...
				</button>
				<ul
					aria-labelledby=""
					class="dropdown-menu dropdown-menu-right"
				>
					<li>
						<button class="dropdown-item" type="button">
							Remove
						</button>
					</li>
					<li>
						<button class="dropdown-item" type="button">
							Download
						</button>
					</li>
					<li>
						<button class="dropdown-item" type="button">
							Checkout
						</button>
					</li>
				</ul>
			</div>
		</div>
	</li>
</ul>

Active

Use the .active class on the same element that you putted .list-group-item.

<ul class="list-group">
	<li class="list-group-item list-group-item-flex active">
		<div class="autofit-col">
			<div class="custom-control custom-checkbox">
				<label>
					<input
						checked
						class="custom-control-input"
						type="checkbox"
					/>
					<span class="custom-control-label"></span>
				</label>
			</div>
		</div>
		<div class="autofit-col">
			<div class="sticker sticker-secondary">
				<span class="inline-item">
					...
				</span>
			</div>
		</div>
		<div class="autofit-col autofit-col-expand">
			<p class="list-group-title text-truncate">
				<a href="#1">Account Example One</a>
			</p>
			<p class="list-group-subtitle text-truncate">Second Level Text</p>
		</div>
		<div class="autofit-col">
			<div class="dropdown dropdown-action">
				...
			</div>
		</div>
	</li>
</ul>