List

A list presents items in one scannable column, such as contacts or settings, and fires an event when a reader chooses one. Its density sets how many items fit on screen, so a short list stays roomy and a long one compact. The lists below are live, each at its own density.

Ana Torres

Ben Okafor

Wi-Fi

Bluetooth

Report.pdf

Notes.txt

Dark mode

Sounds

Off

Budget.xlsx

24 KB

Invoice.pdf

88 KB

Starred

Recent

Weekly sync

Monday, room 4

Design review

Friday, online

Today

Standup

Room 4, with the design team

Friday

Design review

Share the draft first

Mentions

Replies

Inbox

Sent

Drafts

Spam

Starred

Reference docs⁠

Blazor

React

Web

Overview

Examples

API

Styling

Accessibility

Choosing a way to show a collection⁠

Three components show many items at once. Each suits a different job:

List: a column of items to scan and act on, such as contacts or settings.
Data table: read-only rows and columns to compare, such as an invoice or a price table.
Data grid: many rows the reader sorts, selects, and moves through by keyboard, such as an order list of thousands.

One job belongs elsewhere. Splitting a long collection into pages is a paginator, used alongside any of these.

Built in⁠

density sets the height of every item at once, in five steps, and follows your style configuration when omitted.
An item takes a leading or trailing icon as one attribute, leading-icon-name or trailing-icon-name, which a slotted start or end replaces; flip-leading-icon-in-rtl and flip-trailing-icon-in-rtl keep a directional icon pointing the right way.
Overline, supporting text, and trailing supporting text each take a slot, so one row can carry up to three lines.
expressContent builds a list from data: a string is an item, an object is an item with more, and any other object is a divider.
One Tab stop covers the whole list; the arrow keys, Home, and End move between items, and the movement wraps.
One listener on the list hears every choice, whether it comes from the pointer or the keyboard.
An item with href is a link, with the same text and icons as any other item, and target picks where it opens.
value tells your code which item was activated, and disabled makes an item unavailable without removing it.

Using lists well⁠

Choose one, two, or three lines per item by how much supporting text each needs, and give every item in a list the same shape.
Put an icon, avatar, image, or checkbox at the start of an item, and an icon, short text, or a control such as a switch at the end. Use the icon attributes for plain icons and the start and end slots for anything else.
Keep trailing text to a count, a size, or a time, and move longer text to the supporting line.
Order items so they are easy to scan: alphabetical, numerical, chronological, or by the reader's preference.
Add dividers to separate unrelated groups, not to separate every row.
Offer a choice among options as a menu or a select, and keep a list for content a reader acts on.

These rules follow Material 3 Expressive's guidance for lists, on material.io.

Density⁠

density sets the height of every item in the list, in five steps from standard to the densest. Omit it and the list takes its density from your style configuration, which is standard unless you have changed it. A denser step fits more items on screen.

Items⁠

An item holds a headline, with optional overline, supporting, and trailing text, as Lines of text shows. Give every item in one list the same shape.

An item's icons and its disabled state have their own sections: Icons and Disabled.

Lines of text⁠

An item holds a headline, and three slots add text around it: overline above, supporting-text below, and trailing-supporting-text at the end. Supporting text puts a second line under the headline, and an overline with it makes three lines. Trailing text sits at the end of the headline's line and adds none.

Icons⁠

leading-icon-name and trailing-icon-name take a Material Symbols name and draw that icon at the start or end of the item. Content in the start or end slot replaces the named icon. flip-leading-icon-in-rtl and flip-trailing-icon-in-rtl mirror a named icon in a right-to-left layout and leave slotted content alone.

Value⁠

value gives an item a value that its list reports as its own value when someone activates the item by click, Enter, or Space. An item without one reports an empty string. The list fires input and then change on every activation, including a repeat of the same item. The demo shows the value of the item last clicked.

Disabled⁠

disabled makes the item unavailable in place: dimmed, skipped by the keyboard, and ignoring the pointer. The item is not announced as disabled, as the Accessibility tab explains.

Links⁠

Setting href makes the item a link, and target chooses where it opens. target applies only while href is set. Unset, the link opens in the same tab; set it to _blank for a new one. The preview refuses a link that opens a new tab, so the second item below does nothing here.

From data⁠

expressContent builds the items from an array. A string is a one-line item, an object with content is an item with any of the item's own options, and any other object, such as {}, is a divider. Slotted items take precedence over expressContent, with a warning.

Reading a choice⁠

A choice by pointer or keyboard raises input and change on the list, and a repeat of the same item raises them again. The list keeps no selected item. Read the list's value in a change listener to learn which one was chosen: an item's click misses a choice made from the keyboard.

In a settings list⁠

A settings list gives each item a leading icon, a headline, supporting text, and a short trailing value. Keep an unavailable setting in the list, disabled, and say in its supporting text what makes it available.

List

List item

Properties⁠

Property	Attribute	Type	Description
`compareWith`		`(a: TItem, b: TItem) => boolean`	Decides whether an item's value and a selected value name the same item. When set, it is the only test.
`density`	`density0`, `1`, `2`, `3`, `4`	`DensityDensity.Standard`, `.Dense1`, `.Dense2`, `.Dense3`, `.Dense4`default `Density.Standard`, from the style configuration	How tightly items are spaced, from `0`, the roomiest, to `4`, the tightest. See Density.
`expressContent`		`ExpressListElement[]`	The items to show, as an array of `ExpressListItem`, `ExpressListDivider` or `string` elements. An object with no `content` is a divider. Slotted items take precedence, and the list logs a warning when both are set. See From data.
`selectionMode`	`selection-modemulti`, `none`, `single`	`ListSelectionModeListSelectionMode.Multi`, `.None`, `.Single`default `ListSelectionMode.None`	Whether the list holds a selection. `none`, the default, selects nothing: `value` is the value of the item activated last. `single` selects the activated item; `multi` toggles it.
`value`	`value`	`TItem`	The selected item's value, or `null` when nothing is selected. In `multi` mode, the first of `values`. With no selection mode, the value of the item activated last (`""` before any). Set from code it can be any value; a value no item matches is kept, and its item is selected when it arrives. Setting it announces nothing. See Value.
`valueKey`	`value-key`	`string`	The field that identifies an object value: an item whose value has the same field value is selected.
`values`	`values`	`TItem[]`	Every selected item's value, in the order they were selected or written. In `single` mode at most one; with no selection mode, the value of the item activated last. Setting it announces nothing.

Slots⁠

Slot	Description
(default)	A series of `cw-list-item` elements to be shown in the list.

Items are cw-list-item elements. Slotted content for the start or end of an item replaces an icon name set on the same item, with a warning.

Events⁠

Event	Type	Detail	Description
`change`	`SelectionChangeEvent`	`SelectionChangeEventDetail<TItem>`	With no selection mode, fired each time an item is activated, after `input`. In `single` and `multi` mode, fired when the user changes the selection, after `input`. Its detail carries `value` and `values`. It bubbles.
`input`	`InputEvent`	—	Fired on the list before each `change`. It bubbles and is composed.

Props⁠

Prop	Type	Description
`compareWith`	`(a: TItem, b: TItem) => boolean`	Decides whether an item's value and a selected value name the same item. When set, it is the only test.
`density`	`DensityTypeDensity.Standard`, `.Dense1`, `.Dense2`, `.Dense3`, `.Dense4`default `Density.Standard`, from the style configuration	How tightly items are spaced, from `0`, the roomiest, to `4`, the tightest. See Density.
`expressContent`	`ExpressListElement[]`	The items to show, as an array of `ExpressListItem`, `ExpressListDivider` or `string` elements. An object with no `content` is a divider. Slotted items take precedence, and the list logs a warning when both are set. See From data.
`selectionMode`	`ListSelectionModeTypeListSelectionMode.Multi`, `.None`, `.Single`default `ListSelectionMode.None`	Whether the list holds a selection. `none`, the default, selects nothing: `value` is the value of the item activated last. `single` selects the activated item; `multi` toggles it.
`value`	`TItem`	The selected item's value, or `null` when nothing is selected. In `multi` mode, the first of `values`. With no selection mode, the value of the item activated last (`""` before any). Set from code it can be any value; a value no item matches is kept, and its item is selected when it arrives. Setting it announces nothing. See Value.
`valueKey`	`string`	The field that identifies an object value: an item whose value has the same field value is selected.
`values`	`TItem[]`	Every selected item's value, in the order they were selected or written. In `single` mode at most one; with no selection mode, the value of the item activated last. Setting it announces nothing.

Children⁠

Child	Description
`children`	A series of `CrListItem` elements to be shown in the list.

Items are cw-list-item elements. Slotted content for the start or end of an item replaces an icon name set on the same item, with a warning.

Events⁠

Prop	Argument	Description
`onChange`	`SelectionChangeEvent<TItem>`	With no selection mode, fired each time an item is activated, after `input`. In `single` and `multi` mode, fired when the user changes the selection, after `input`. Its detail carries `value` and `values`. It bubbles. Its `detail` carries `value` and `values`.
`onInput`	`React.ChangeEvent<HTMLInputElement>`	Fired on the list before each `change`. It bubbles and is composed.

Parameters⁠

Parameter	Type	Description
`Density`	`Density?Density.Standard`, `.Dense1`, `.Dense2`, `.Dense3`, `.Dense4`default `Density.Standard`, from the style configuration	How tightly items are spaced, from `0`, the roomiest, to `4`, the tightest. See Density.
`ExpressContent`	`IEnumerable<ExpressListElement>?`	The items to show, as an array of `ExpressListItem`, `ExpressListDivider` or `string` elements. An object with no `content` is a divider. Slotted items take precedence, and the list logs a warning when both are set. See From data.
`SelectionMode`	`ListSelectionMode?ListSelectionMode.Multi`, `.None`, `.Single`default `ListSelectionMode.None`	Whether the list holds a selection. `none`, the default, selects nothing: `Value` is the value of the item activated last. `single` selects the activated item; `multi` toggles it.
`Value`	`TItem`	The selected item's value, or `null` when nothing is selected. In `multi` mode, the first of `Values`. With no selection mode, the value of the item activated last (`""` before any). Set from code it can be any value; a value no item matches is kept, and its item is selected when it arrives. Setting it announces nothing. See Value.
`ValueExpression`	`Expression<Func<TItem>>?`	Gets or sets an expression that identifies the bound value.
`Values`	`IList<TItem>`	Every selected item's value, in the order they were selected or written. In `single` mode at most one; with no selection mode, the value of the item activated last. Setting it announces nothing.
`ValuesExpression`	`Expression<Func<IList<TItem>>>?`	Gets or sets an expression that identifies the bound value.

Render fragments⁠

Parameter	Type	Description
`ChildContent`	`RenderFragment?`	A series of `CbListItem` elements to be shown in the list.

Items are cw-list-item elements. Slotted content for the start or end of an item replaces an icon name set on the same item, with a warning.

Event callbacks⁠

Parameter	Type	Description
`OnChange`	`EventCallback<SelectionChangeEventArgs<TItem>>`	With no selection mode, fired each time an item is activated, after `input`. In `single` and `multi` mode, fired when the user changes the selection, after `input`. Its detail carries `Value` and `Values`. It bubbles. Its `detail` carries `Value` and `Values`.
`OnInput`	`EventCallback<ChangeEventArgs>`	Fired on the list before each `change`. It bubbles and is composed.

Inputs⁠

Input	Type	Description
`compareWith`	`(a: TItem, b: TItem) => boolean`	Decides whether an item's value and a selected value name the same item. When set, it is the only test.
`density`	`DensityTypeDensity.Standard`, `.Dense1`, `.Dense2`, `.Dense3`, `.Dense4`default `Density.Standard`, from the style configuration	How tightly items are spaced, from `0`, the roomiest, to `4`, the tightest. See Density.
`expressContent`	`ExpressListElement[]`	The items to show, as an array of `ExpressListItem`, `ExpressListDivider` or `string` elements. An object with no `content` is a divider. Slotted items take precedence, and the list logs a warning when both are set. See From data.
`selectionMode`	`ListSelectionModeTypeListSelectionMode.Multi`, `.None`, `.Single`default `ListSelectionMode.None`	Whether the list holds a selection. `none`, the default, selects nothing: `value` is the value of the item activated last. `single` selects the activated item; `multi` toggles it.
`value`	`TItem`	The selected item's value, or `null` when nothing is selected. In `multi` mode, the first of `values`. With no selection mode, the value of the item activated last (`""` before any). Set from code it can be any value; a value no item matches is kept, and its item is selected when it arrives. Setting it announces nothing. See Value.
`valueKey`	`string`	The field that identifies an object value: an item whose value has the same field value is selected.
`values`	`TItem[]`	Every selected item's value, in the order they were selected or written. In `single` mode at most one; with no selection mode, the value of the item activated last. Setting it announces nothing.

Content projection⁠

Content	Description
content with no `slot`	A series of `CaListItem` elements to be shown in the list.

Items are cw-list-item elements. Slotted content for the start or end of an item replaces an icon name set on the same item, with a warning.

Outputs⁠

Output	Event	Description
`cwChange`	`SelectionChangeEvent`	With no selection mode, fired each time an item is activated, after `input`. In `single` and `multi` mode, fired when the user changes the selection, after `input`. Its detail carries `value` and `values`. It bubbles. Its `detail` carries `value` and `values`.
`cwInput`	`InputEvent`	Fired on the list before each `change`. It bubbles and is composed.

Props⁠

Prop	Type	Description
`compareWith`	`(a: TItem, b: TItem) => boolean`	Decides whether an item's value and a selected value name the same item. When set, it is the only test.
`density`	`DensityTypeDensity.Standard`, `.Dense1`, `.Dense2`, `.Dense3`, `.Dense4`default `Density.Standard`, from the style configuration	How tightly items are spaced, from `0`, the roomiest, to `4`, the tightest. See Density.
`expressContent`	`ExpressListElement[]`	The items to show, as an array of `ExpressListItem`, `ExpressListDivider` or `string` elements. An object with no `content` is a divider. Slotted items take precedence, and the list logs a warning when both are set. See From data.
`selectionMode`	`ListSelectionModeTypeListSelectionMode.Multi`, `.None`, `.Single`default `ListSelectionMode.None`	Whether the list holds a selection. `none`, the default, selects nothing: `value` is the value of the item activated last. `single` selects the activated item; `multi` toggles it.
`value`	`TItem`	The selected item's value, or `null` when nothing is selected. In `multi` mode, the first of `values`. With no selection mode, the value of the item activated last (`""` before any). Set from code it can be any value; a value no item matches is kept, and its item is selected when it arrives. Setting it announces nothing. See Value.
`valueKey`	`string`	The field that identifies an object value: an item whose value has the same field value is selected.
`values`	`TItem[]`	Every selected item's value, in the order they were selected or written. In `single` mode at most one; with no selection mode, the value of the item activated last. Setting it announces nothing.

Slots⁠

Slot	Description
`default`	A series of `CvListItem` elements to be shown in the list.

Items are cw-list-item elements. Slotted content for the start or end of an item replaces an icon name set on the same item, with a warning.

Events⁠

Event	Type	Description
`change`	`SelectionChangeEvent`	With no selection mode, fired each time an item is activated, after `input`. In `single` and `multi` mode, fired when the user changes the selection, after `input`. Its detail carries `value` and `values`. It bubbles. Its `detail` carries `value` and `values`.
`input`	`InputEvent`	Fired on the list before each `change`. It bubbles and is composed.

Props⁠

Prop	Type	Description
`compareWith`	`(a: TItem, b: TItem) => boolean`	Decides whether an item's value and a selected value name the same item. When set, it is the only test.
`density`	`DensityTypeDensity.Standard`, `.Dense1`, `.Dense2`, `.Dense3`, `.Dense4`default `Density.Standard`, from the style configuration	How tightly items are spaced, from `0`, the roomiest, to `4`, the tightest. See Density.
`expressContent`	`ExpressListElement[]`	The items to show, as an array of `ExpressListItem`, `ExpressListDivider` or `string` elements. An object with no `content` is a divider. Slotted items take precedence, and the list logs a warning when both are set. See From data.
`selectionMode`	`ListSelectionModeTypeListSelectionMode.Multi`, `.None`, `.Single`default `ListSelectionMode.None`	Whether the list holds a selection. `none`, the default, selects nothing: `value` is the value of the item activated last. `single` selects the activated item; `multi` toggles it.
`value`	`TItem`	The selected item's value, or `null` when nothing is selected. In `multi` mode, the first of `values`. With no selection mode, the value of the item activated last (`""` before any). Set from code it can be any value; a value no item matches is kept, and its item is selected when it arrives. Setting it announces nothing. See Value.
`valueKey`	`string`	The field that identifies an object value: an item whose value has the same field value is selected.
`values`	`TItem[]`	Every selected item's value, in the order they were selected or written. In `single` mode at most one; with no selection mode, the value of the item activated last. Setting it announces nothing.

Snippets⁠

Snippet	Description
`children`	A series of `CsListItem` elements to be shown in the list.

Items are cw-list-item elements. Slotted content for the start or end of an item replaces an icon name set on the same item, with a warning.

Events⁠

Prop	Type	Description
`onChange`	`SelectionChangeEvent`	With no selection mode, fired each time an item is activated, after `input`. In `single` and `multi` mode, fired when the user changes the selection, after `input`. Its detail carries `value` and `values`. It bubbles. Its `detail` carries `value` and `values`.
`onInput`	`InputEvent`	Fired on the list before each `change`. It bubbles and is composed.

Properties⁠

Property	Attribute	Type	Description
`disabled`	`disabled`	`boolean`default `false`	Removes the item from the tab and arrow-key order, dims it and ignores the pointer. It sets no `aria-disabled`. See Disabled.
`download`	`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipLeadingIconInRtl`	`flip-leading-icon-in-rtl`	`boolean`default `false`	Flips the leading icon supplied in `leading-icon-name` when the text direction is right to left. See Icons.
`flipTrailingIconInRtl`	`flip-trailing-icon-in-rtl`	`boolean`default `false`	Flips the trailing icon supplied in `trailing-icon-name` when the text direction is right to left. See Icons.
`href`	`href`	`string`	The URL the element links to. While it is set, the element is a link. See Links.
`leadingIconName`	`leading-icon-name`	`string`	A leading Material Symbols icon name. This is an alternative to the `start` slot. If both are provided, the `start` slot takes precedence. See Icons.
`rel`	`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`selected`	`selected`	`boolean`default `false`	Whether the item is selected. A selected item paints its selected container. In a list with a selection mode, the list sets it from its own `value` or `values`.
`target`	`target_blank`, `_self`, `_parent`, `_top`, `""`	`UrlTargetUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where the link opens `href`. Empty, it opens in the same tab. Ignored unless `href` is set. See Links.
`touchTarget`	`touch-targetnone`, `overflow`, `wrapper`	`TouchTargetTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size.
`trailingIconName`	`trailing-icon-name`	`string`	A trailing Material Symbols icon name. This is an alternative to the `end` slot. If both are provided, the `end` slot takes precedence. See Icons.
`value`	`value`	`unknown`	The item's value: the parent reports it as its own `value` when this item is chosen. Set from code it can be any value, such as a number or an object; the `value` attribute sets it to a string. See Value.

Slots⁠

Slot	Description
`container`	Content shown behind the item, such as a background image.
`overline`	A small text snippet above the headline.
(default)	The headline/custom content.
`supporting-text`	Supporting text lines underneath the headline.
`start`	Any leading content, such as icons, avatars, or checkboxes.
`end`	Any trailing content, such as icons and buttons.
`trailing-supporting-text`	A small text snippet at the end of the item.

Events⁠

Event	Type	Detail	Description
`link-activate`	`LinkActivateEvent`	`LinkActivateEventDetail`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable.
`click`	`MouseEvent`	—	Dispatched when the item is clicked. It bubbles, is composed, and is cancelable.

Props⁠

Prop	Type	Description
`disabled`	`boolean`default `false`	Removes the item from the tab and arrow-key order, dims it and ignores the pointer. It sets no `aria-disabled`. See Disabled.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipLeadingIconInRtl`	`boolean`default `false`	Flips the leading icon supplied in `leadingIconName` when the text direction is right to left. See Icons.
`flipTrailingIconInRtl`	`boolean`default `false`	Flips the trailing icon supplied in `trailingIconName` when the text direction is right to left. See Icons.
`href`	`string`	The URL the element links to. While it is set, the element is a link. See Links.
`leadingIconName`	`string`	A leading Material Symbols icon name. This is an alternative to the `slot="start"` child. If both are provided, the `slot="start"` child takes precedence. See Icons.
`onNavigate`	`(detail: LinkActivateEventDetail, event: LinkActivateEvent) => void`	Called when the link points inside the app: the same origin, opening in the same tab. The browser's navigation is canceled first, so this handler navigates, and it replaces the navigation `ChameleonRouterProvider` would make.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`selected`	`boolean`default `false`	Whether the item is selected. A selected item paints its selected container. In a list with a selection mode, the list sets it from its own `value` or `values`.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where the link opens `href`. Empty, it opens in the same tab. Ignored unless `href` is set. See Links.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size.
`trailingIconName`	`string`	A trailing Material Symbols icon name. This is an alternative to the `slot="end"` child. If both are provided, the `slot="end"` child takes precedence. See Icons.
`value`	`unknown`	The item's value: the parent reports it as its own `value` when this item is chosen. Set from code it can be any value, such as a number or an object; the `value` attribute sets it to a string. See Value.

Children⁠

Child	Description
a child with `slot="container"`	Content shown behind the item, such as a background image.
a child with `slot="overline"`	A small text snippet above the headline.
`children`	The headline/custom content.
a child with `slot="supporting-text"`	Supporting text lines underneath the headline.
a child with `slot="start"`	Any leading content, such as icons, avatars, or checkboxes.
a child with `slot="end"`	Any trailing content, such as icons and buttons.
a child with `slot="trailing-supporting-text"`	A small text snippet at the end of the item.

Events⁠

Prop	Argument	Description
`onLinkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`onClick`	`React.MouseEvent<HTMLElement>`	Dispatched when the item is clicked. It bubbles, is composed, and is cancelable.

Parameters⁠

Parameter	Type	Description
`Disabled`	`bool?`default `false`	Removes the item from the tab and arrow-key order, dims it and ignores the pointer. It sets no `aria-disabled`. See Disabled.
`Download`	`string?`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `Href` is set.
`FlipLeadingIconInRtl`	`bool?`default `false`	Flips the leading icon supplied in `LeadingIconName` when the text direction is right to left. See Icons.
`FlipTrailingIconInRtl`	`bool?`default `false`	Flips the trailing icon supplied in `TrailingIconName` when the text direction is right to left. See Icons.
`Href`	`string?`	The URL the element links to. While it is set, the element is a link. See Links.
`LeadingIconName`	`string?`	A leading Material Symbols icon name. This is an alternative to the `Start` render fragment. If both are provided, the `Start` render fragment takes precedence. See Icons.
`OnNavigate`	`EventCallback<LinkActivateEventArgs>`	Navigates for a link that points inside the app: the same base address, opening in the same tab. The browser's navigation is canceled first, and this callback replaces the NavigationManager.NavigateTo the component calls by default. It is not called for any other link.
`Rel`	`string?`	The link's relationship to the linked URL, as the anchor's `Rel`, used exactly as given. Unset, the anchor has no `Rel`. Ignored unless `Href` is set.
`Selected`	`bool?`default `false`	Whether the item is selected. A selected item paints its selected container. In a list with a selection mode, the list sets it from its own `Value` or `values`.
`Target`	`UrlTarget?UrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where the link opens `Href`. Empty, it opens in the same tab. Ignored unless `Href` is set. See Links.
`TouchTarget`	`TouchTarget?TouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size.
`TrailingIconName`	`string?`	A trailing Material Symbols icon name. This is an alternative to the `End` render fragment. If both are provided, the `End` render fragment takes precedence. See Icons.
`Value`	`TItem`	The item's value: the parent reports it as its own `Value` when this item is chosen. Set from code it can be any value, such as a number or an object; the `Value` attribute sets it to a string. See Value.

Render fragments⁠

Once you write Container or any other fragment as a child element, the main content must go in an explicit <ChildContent> too; markup beside <Container> is a compile error. Here ChildContent is: The headline/custom content.

<CbListItem>
    <Container>Content</Container>
    <ChildContent>Main content</ChildContent>
</CbListItem>

content_copy

Parameter	Type	Description
`ChildContent`	`RenderFragment?`	The headline/custom content.
`Container`	`RenderFragment?`	Content shown behind the item, such as a background image.
`End`	`RenderFragment?`	Any trailing content, such as icons and buttons.
`Overline`	`RenderFragment?`	A small text snippet above the headline.
`Start`	`RenderFragment?`	Any leading content, such as icons, avatars, or checkboxes.
`SupportingText`	`RenderFragment?`	Supporting text lines underneath the headline.
`TrailingSupportingText`	`RenderFragment?`	A small text snippet at the end of the item.

Event callbacks⁠

Parameter	Type	Description
`OnLinkActivate`	`EventCallback<LinkActivateEventArgs>`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `Href`, `Target`, `Download`, `Rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`OnClick`	`EventCallback<MouseEventArgs>`	Dispatched when the item is clicked. It bubbles, is composed, and is cancelable.

Inputs⁠

Input	Type	Description
`disabled`	`boolean`default `false`	Removes the item from the tab and arrow-key order, dims it and ignores the pointer. It sets no `aria-disabled`. See Disabled.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipLeadingIconInRtl`	`boolean`default `false`	Flips the leading icon supplied in `leadingIconName` when the text direction is right to left. See Icons.
`flipTrailingIconInRtl`	`boolean`default `false`	Flips the trailing icon supplied in `trailingIconName` when the text direction is right to left. See Icons.
`href`	`string`	The URL the element links to. While it is set, the element is a link. See Links.
`leadingIconName`	`string`	A leading Material Symbols icon name. This is an alternative to the `start` slot. If both are provided, the `start` slot takes precedence. See Icons.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`selected`	`boolean`default `false`	Whether the item is selected. A selected item paints its selected container. In a list with a selection mode, the list sets it from its own `value` or `values`.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where the link opens `href`. Empty, it opens in the same tab. Ignored unless `href` is set. See Links.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size.
`trailingIconName`	`string`	A trailing Material Symbols icon name. This is an alternative to the `end` slot. If both are provided, the `end` slot takes precedence. See Icons.
`value`	`unknown`	The item's value: the parent reports it as its own `value` when this item is chosen. Set from code it can be any value, such as a number or an object; the `value` attribute sets it to a string. See Value.

Content projection⁠

Content	Description
an element with `slot="container"`	Content shown behind the item, such as a background image.
an element with `slot="overline"`	A small text snippet above the headline.
content with no `slot`	The headline/custom content.
an element with `slot="supporting-text"`	Supporting text lines underneath the headline.
an element with `slot="start"`	Any leading content, such as icons, avatars, or checkboxes.
an element with `slot="end"`	Any trailing content, such as icons and buttons.
an element with `slot="trailing-supporting-text"`	A small text snippet at the end of the item.

Outputs⁠

Output	Event	Description
`cwLinkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`cwClick`	`MouseEvent`	Dispatched when the item is clicked. It bubbles, is composed, and is cancelable.

Props⁠

Prop	Type	Description
`disabled`	`boolean`default `false`	Removes the item from the tab and arrow-key order, dims it and ignores the pointer. It sets no `aria-disabled`. See Disabled.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipLeadingIconInRtl`	`boolean`default `false`	Flips the leading icon supplied in `leadingIconName` when the text direction is right to left. See Icons.
`flipTrailingIconInRtl`	`boolean`default `false`	Flips the trailing icon supplied in `trailingIconName` when the text direction is right to left. See Icons.
`href`	`string`	The URL the element links to. While it is set, the element is a link. See Links.
`leadingIconName`	`string`	A leading Material Symbols icon name. This is an alternative to the `start` slot. If both are provided, the `start` slot takes precedence. See Icons.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`selected`	`boolean`default `false`	Whether the item is selected. A selected item paints its selected container. In a list with a selection mode, the list sets it from its own `value` or `values`.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where the link opens `href`. Empty, it opens in the same tab. Ignored unless `href` is set. See Links.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size.
`trailingIconName`	`string`	A trailing Material Symbols icon name. This is an alternative to the `end` slot. If both are provided, the `end` slot takes precedence. See Icons.
`value`	`unknown`	The item's value: the parent reports it as its own `value` when this item is chosen. Set from code it can be any value, such as a number or an object; the `value` attribute sets it to a string. See Value.

Slots⁠

Slot	Description
`default`	The headline/custom content.
`container`	Content shown behind the item, such as a background image.
`end`	Any trailing content, such as icons and buttons.
`overline`	A small text snippet above the headline.
`start`	Any leading content, such as icons, avatars, or checkboxes.
`supporting-text`	Supporting text lines underneath the headline.
`trailing-supporting-text`	A small text snippet at the end of the item.

Events⁠

Event	Type	Description
`linkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`click`	`MouseEvent`	Dispatched when the item is clicked. It bubbles, is composed, and is cancelable.

Props⁠

Prop	Type	Description
`disabled`	`boolean`default `false`	Removes the item from the tab and arrow-key order, dims it and ignores the pointer. It sets no `aria-disabled`. See Disabled.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipLeadingIconInRtl`	`boolean`default `false`	Flips the leading icon supplied in `leadingIconName` when the text direction is right to left. See Icons.
`flipTrailingIconInRtl`	`boolean`default `false`	Flips the trailing icon supplied in `trailingIconName` when the text direction is right to left. See Icons.
`href`	`string`	The URL the element links to. While it is set, the element is a link. See Links.
`leadingIconName`	`string`	A leading Material Symbols icon name. This is an alternative to the `startSnippet` snippet. If both are provided, the `startSnippet` snippet takes precedence. See Icons.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`selected`	`boolean`default `false`	Whether the item is selected. A selected item paints its selected container. In a list with a selection mode, the list sets it from its own `value` or `values`.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where the link opens `href`. Empty, it opens in the same tab. Ignored unless `href` is set. See Links.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size.
`trailingIconName`	`string`	A trailing Material Symbols icon name. This is an alternative to the `endSnippet` snippet. If both are provided, the `endSnippet` snippet takes precedence. See Icons.
`value`	`unknown`	The item's value: the parent reports it as its own `value` when this item is chosen. Set from code it can be any value, such as a number or an object; the `value` attribute sets it to a string. See Value.

Snippets⁠

Snippet	Description
`containerSnippet`	Content shown behind the item, such as a background image.
`overlineSnippet`	A small text snippet above the headline.
`children`	The headline/custom content.
`supportingTextSnippet`	Supporting text lines underneath the headline.
`startSnippet`	Any leading content, such as icons, avatars, or checkboxes.
`endSnippet`	Any trailing content, such as icons and buttons.
`trailingSupportingTextSnippet`	A small text snippet at the end of the item.

Events⁠

Prop	Type	Description
`onLinkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`onClick`	`MouseEvent`	Dispatched when the item is clicked. It bubbles, is composed, and is cancelable.

List

List item

A value is what the token defaults to; selecting it copies the token's name.

Tokens⁠

Token	Value
`--ct-list-list-layers-container-color`	`--ct-sys-color-surface` `--ct-list-list-layers-container-color`

A value is what the token defaults to; selecting it copies the token's name.

Tokens⁠

Names and states⁠

A screen reader announces the list as a list and each item as a list item. The WAI-ARIA Authoring Practices Guide has no pattern for a static list. The keys below follow the WAI-ARIA Authoring Practices: Listbox pattern: one Tab stop for the whole list, and the arrow keys inside it.

The list takes its name from its aria-label. Give every list one.
An item takes its name from its text: a screen reader reads its overline, headline, supporting text, and trailing supporting text. Of the ARIA attributes set on an item, only aria-label, aria-selected, aria-current, aria-checked, aria-expanded, and aria-haspopup take effect; any other has no effect.
The list does not mark an item as current. Set aria-current on the item that is the reader's current place, such as the current page or step; that item is announced as current and its row is filled.
A screen reader announces a linked item as a list item, not as a link. Write item text that says where the link goes.
A screen reader does not announce a disabled item as disabled; it reads as an ordinary item that does nothing. Say in the item's text that it is unavailable.
The list has no selected state. For a choice among options, use a menu or a select; to compare values across columns, use a data table.

Keyboard and focus⁠

Key	Action
Tab	Moves focus into the list, and out of the list to the next control.
Arrow Down, Arrow Right	Moves to the next item, and from the last item to the first.
Arrow Up, Arrow Left	Moves to the previous item, and from the first item to the last.
Home, End	Moves to the first or last item.
Enter, Space	Activates the focused item.

Tab is the browser's own behavior, and the other keys are the list's. A right-to-left layout swaps the two horizontal arrow keys.

Only one item in the list is in the Tab order at a time. Clicking an item, then pressing Tab, moves focus on from that item.
Arrow movement skips disabled items, and a disabled item has no tab stop.
The list has no typeahead.
An item draws a focus ring on keyboard focus.

Pointer and touch⁠

An item is a full-width row, so its width never limits the target. It is at least 56 pixels tall by default, and density shortens it by up to 20 pixels, to 36 at the densest setting, as Density shows; every setting clears the 24 by 24 pixels of WCAG 2.5.8.
A disabled item ignores the pointer.

Display settings⁠

Forced colors: a disabled item draws in GrayText at full opacity. The rest of the list follows the system colors.
Reduced motion: the list defines no animation or transition, so there is nothing to stop.
Right-to-left: the Left and Right arrow keys swap. An item's padding follows the text direction. An icon set by leading-icon-name or trailing-icon-name mirrors only when flip-leading-icon-in-rtl or flip-trailing-icon-in-rtl is set, and slotted content never mirrors.

Standards⁠

With its defaults, the list meets four WCAG 2.2 success criteria:

1.3.1 Info and Relationships (A)
2.1.1 Keyboard (A)
2.4.7 Focus Visible (AA)
2.5.8 Target Size (Minimum) (AA)

Three more depend on how you use it:

1.1.1 Non-text Content (A): give a slotted image an alt text, or mark a decorative one so a screen reader skips it.
2.4.4 Link Purpose (In Context) (A): write linked item text that says where the link goes.
4.1.2 Name, Role, Value (A): give the list an aria-label, and state in the item's text when an item is unavailable.

Token	Value
`--ct-list-item-bottom-space`	`12px` `--ct-list-item-bottom-space`
`--ct-list-item-disabled-opacity`	`0.38` `--ct-list-item-disabled-opacity`
`--ct-list-item-hover-state-layer-color`	`--ct-sys-color-on-surface` `--ct-list-item-hover-state-layer-color`
`--ct-list-item-hover-state-layer-opacity`	`--ct-sys-state-hover-state-layer-opacity` `--ct-list-item-hover-state-layer-opacity`
`--ct-list-item-label-text-color`	`--ct-sys-color-on-surface` `--ct-list-item-label-text-color`
`--ct-list-item-label-text-font`	`--ct-sys-typescale-body-large-font` `--ct-list-item-label-text-font`
`--ct-list-item-label-text-line-height`	`--ct-sys-typescale-body-large-line-height` `--ct-list-item-label-text-line-height`
`--ct-list-item-label-text-size`	`--ct-sys-typescale-body-large-size` `--ct-list-item-label-text-size`
`--ct-list-item-label-text-tracking`	`--ct-sys-typescale-body-large-tracking` `--ct-list-item-label-text-tracking`
`--ct-list-item-label-text-weight`	`--ct-sys-typescale-body-large-weight` `--ct-list-item-label-text-weight`
`--ct-list-item-leading-icon-color`	`--ct-sys-color-on-surface-variant` `--ct-list-item-leading-icon-color`
`--ct-list-item-leading-icon-size`	`24px` `--ct-list-item-leading-icon-size`
`--ct-list-item-leading-space`	`16px` `--ct-list-item-leading-space`
`--ct-list-item-one-line-container-height`	`56px` `--ct-list-item-one-line-container-height`
`--ct-list-item-overline-color`	`--ct-sys-color-on-surface-variant` `--ct-list-item-overline-color`
`--ct-list-item-overline-font`	`--ct-sys-typescale-label-small-font` `--ct-list-item-overline-font`
`--ct-list-item-overline-line-height`	`--ct-sys-typescale-label-small-line-height` `--ct-list-item-overline-line-height`
`--ct-list-item-overline-size`	`--ct-sys-typescale-label-small-size` `--ct-list-item-overline-size`
`--ct-list-item-overline-tracking`	`--ct-sys-typescale-label-small-tracking` `--ct-list-item-overline-tracking`
`--ct-list-item-overline-weight`	`--ct-sys-typescale-label-small-weight` `--ct-list-item-overline-weight`
`--ct-list-item-pressed-state-layer-color`	`--ct-sys-color-on-surface` `--ct-list-item-pressed-state-layer-color`
`--ct-list-item-pressed-state-layer-opacity`	`--ct-sys-state-pressed-state-layer-opacity` `--ct-list-item-pressed-state-layer-opacity`
`--ct-list-item-selected-container-color`	`--ct-sys-color-secondary-container` `--ct-list-item-selected-container-color`
`--ct-list-item-selected-label-text-color`	same as `--ct-list-item-label-text-color` `--ct-list-item-selected-label-text-color`
`--ct-list-item-selected-leading-icon-color`	same as `--ct-list-item-leading-icon-color` `--ct-list-item-selected-leading-icon-color`
`--ct-list-item-selected-trailing-icon-color`	same as `--ct-list-item-trailing-icon-color` `--ct-list-item-selected-trailing-icon-color`
`--ct-list-item-supporting-text-color`	`--ct-sys-color-on-surface-variant` `--ct-list-item-supporting-text-color`
`--ct-list-item-supporting-text-font`	`--ct-sys-typescale-body-medium-font` `--ct-list-item-supporting-text-font`
`--ct-list-item-supporting-text-line-height`	`--ct-sys-typescale-body-medium-line-height` `--ct-list-item-supporting-text-line-height`
`--ct-list-item-supporting-text-size`	`--ct-sys-typescale-body-medium-size` `--ct-list-item-supporting-text-size`
`--ct-list-item-supporting-text-tracking`	`--ct-sys-typescale-body-medium-tracking` `--ct-list-item-supporting-text-tracking`
`--ct-list-item-supporting-text-weight`	`--ct-sys-typescale-body-medium-weight` `--ct-list-item-supporting-text-weight`
`--ct-list-item-top-space`	`12px` `--ct-list-item-top-space`
`--ct-list-item-trailing-icon-color`	`--ct-sys-color-on-surface-variant` `--ct-list-item-trailing-icon-color`
`--ct-list-item-trailing-icon-size`	`24px` `--ct-list-item-trailing-icon-size`
`--ct-list-item-trailing-space`	`16px` `--ct-list-item-trailing-space`
`--ct-list-item-trailing-supporting-text-color`	`--ct-sys-color-on-surface-variant` `--ct-list-item-trailing-supporting-text-color`
`--ct-list-item-trailing-supporting-text-font`	`--ct-sys-typescale-label-small-font` `--ct-list-item-trailing-supporting-text-font`
`--ct-list-item-trailing-supporting-text-line-height`	`--ct-sys-typescale-label-small-line-height` `--ct-list-item-trailing-supporting-text-line-height`
`--ct-list-item-trailing-supporting-text-size`	`--ct-sys-typescale-label-small-size` `--ct-list-item-trailing-supporting-text-size`
`--ct-list-item-trailing-supporting-text-tracking`	`--ct-sys-typescale-label-small-tracking` `--ct-list-item-trailing-supporting-text-tracking`
`--ct-list-item-trailing-supporting-text-weight`	`--ct-sys-typescale-label-small-weight` `--ct-list-item-trailing-supporting-text-weight`

List

Reference docs⁠link

Choosing a way to show a collection⁠link

Built in⁠link

Using lists well⁠link

Density⁠link

Items⁠link

Lines of text⁠link

Icons⁠link

Value⁠link

Disabled⁠link

Links⁠link

From data⁠link

Reading a choice⁠link

In a settings list⁠link

Properties⁠link

Slots⁠link

Events⁠link

Props⁠link

Children⁠link

Events⁠link

Parameters⁠link

Render fragments⁠link

Event callbacks⁠link

Inputs⁠link

Content projection⁠link

Outputs⁠link

Props⁠link

Slots⁠link

Events⁠link

Props⁠link

Snippets⁠link

Events⁠link

Properties⁠link

Slots⁠link

Events⁠link

Props⁠link

Children⁠link

Events⁠link

Parameters⁠link

Render fragments⁠link

Event callbacks⁠link

Inputs⁠link

Content projection⁠link

Outputs⁠link

Props⁠link

Slots⁠link

Events⁠link

Props⁠link

Snippets⁠link

Events⁠link

Tokens⁠link

Tokens⁠link

Names and states⁠link

Keyboard and focus⁠link

Pointer and touch⁠link

Display settings⁠link

Standards⁠link

Reference docs⁠

Choosing a way to show a collection⁠

Built in⁠

Using lists well⁠

Density⁠

Items⁠

Lines of text⁠

Icons⁠

Value⁠

Disabled⁠

Links⁠

From data⁠

Reading a choice⁠

In a settings list⁠

Properties⁠

Slots⁠

Events⁠

Props⁠

Children⁠

Events⁠

Parameters⁠

Render fragments⁠

Event callbacks⁠

Inputs⁠

Content projection⁠

Outputs⁠

Props⁠

Slots⁠

Events⁠

Props⁠

Snippets⁠

Events⁠

Properties⁠

Slots⁠

Events⁠

Props⁠

Children⁠

Events⁠

Parameters⁠

Render fragments⁠

Event callbacks⁠

Inputs⁠

Content projection⁠

Outputs⁠

Props⁠

Slots⁠

Events⁠

Props⁠

Snippets⁠

Events⁠

Tokens⁠

Tokens⁠

Names and states⁠

Keyboard and focus⁠

Pointer and touch⁠

Display settings⁠

Standards⁠