Props

List

Name	Type	Default	Description
density	ListDensity	'balanced'	Spacing density for the rows: compact (4px of block padding), balanced (8px), or spacious (12px, which also widens the inline padding by one step). A single row can override it with its own density.
hasDividers	boolean	false	Whether to rule a line between neighbouring rows. The last row never draws one, and rows lose their rounded corners while dividers are on.
edgeCompensation	'inline'	-	Cancels each row's inline inset, up to the container padding published on each edge, so row text lines up with a sibling heading. It reads --container-padding-inline-start and --container-padding-inline-end and treats a missing value as zero, so a row is never pulled outside its container. Omitting the prop leaves row positions unchanged.
listStyle	ListMarkerStyle	'none'	The marker drawn in front of each row: none, disc (filled bullet), circle (outlined bullet), or decimal (numbers). decimal renders the list as an <ol>.
start	number	1	The first number of an ordered list, only used when listStyle="decimal". It is written both to the start attribute of the <ol> and to the CSS counter.
header	string	-	Plain-text title rendered above the list and associated with it through aria-labelledby. Use the header slot for rich content.

ListItem

Name	Type	Default	Description
label	string | number	-	The primary text identifying the row. A string or a number truncates to one line; use the label slot for rich content.
description	string | number	-	Secondary text below the label, also truncated to one line. Use the description slot for multiple lines or rich content.
density	ItemDensity	-	Overrides the density of the surrounding List. When omitted the row inherits the list's density, or balanced outside a list.
onClick	(event: MouseEvent) => void	-	Click handler. It renders a button that fills the row's content area and enables the hover and pressed states. Write @click in a template.
interactiveRef	MaybeRefOrGetter<HTMLElement | null | undefined>	-	A ref to a control inside the row that already carries its keyboard access and action, such as a checkbox in startContent. The row becomes an enlarged click target that forwards surface clicks to that control and renders no button of its own, so it adds no second tab stop. Mutually exclusive with onClick and href, which are ignored while it is set.
href	string	-	Link URL. A link element is rendered inside the row.
target	'_blank' | '_self'	-	Where the link opens, only used with href. _blank automatically adds noopener and noreferrer.
rel	string	-	Link relationship tokens, merged and de-duplicated with the ones added automatically.
isDisabled	boolean	false	Disabled state. The row becomes inert, its content dims, and aria-disabled="true" is written. A row that carries its own role is left non-inert, because its parent owns the interaction.
isSelected	boolean	false	Selected state. Written as aria-selected="true" when the role permits it, and as aria-current="true" otherwise. An aria-current you pass yourself wins.

Item

Name	Type	Default	Description
as	string | Component	'div'	The root element. Give a component only when the row carries a role, so the parent keeps keyboard access and the row adds no second tab stop.
align	'center' | 'start'	'center'	Vertical alignment of the start and end content slots. Use start when either end is taller than one line of text.
labelLines	number	-	Maximum lines before the label truncates. A string label truncates to one line when this is omitted; slot content is never truncated.
descriptionLines	number	-	Maximum lines before the description truncates. A string description truncates to one line when this is omitted; slot content is left alone in a stacked layout.
layout	'stacked' | 'inline'	'stacked'	How the label and description sit together. inline shares one line and ellipsizes the description first, keeping the row height fixed for hosts such as a trigger.
isHighlighted	boolean	false	The highlighted appearance, which is what keyboard focus and hover paint. Menu-like components use it for the row they have moved to.

Item also accepts everything ListItem accepts: label, description, density, onClick, interactiveRef, href, target, rel, isDisabled, and isSelected.

Slots

List

Name	Description
default	The entries of the list, usually ListItem.
header	Content rendered above the list, associated with it through aria-labelledby.

ListItem / Item

Name	Description
startContent	Content before the label: an icon, an avatar, or a checkbox.
label	Rich content replacing the label prop. It is exempt from the automatic truncation.
description	Rich content replacing the description prop.
endContent	Content after the label: a badge, a timestamp, or a chevron.
marker	The marker drawn at the head of the row as a direct child. Item exposes it; ListItem fills it from the list's listStyle.

Exposed

Name	Signature	Description
element	ComputedRef<HTMLUListElement | HTMLOListElement | null>	The list element itself. A list with a header is wrapped, and this is still the list element inside the wrapper.

ListItem and Item also expose element (the root element), focus(), and blur(); focusing lands on the control inside the row that can actually take focus.

Native attributes

List

The root element is a <ul>, or an <ol> when listStyle="decimal". A header adds a wrapper element around it.

The following go to the list element:

• HTML attributes.
• aria-* attributes.
• data-* attributes.
• class.
• style.

The component writes role="list", data-density, data-dividers, data-list-style, and data-edge-compensation. Without a rendered header an aria-labelledby you pass is kept; with one, the list's own header takes over.

ListItem / Item

The root element is a <div> by default, and an <li> for ListItem.

The following go to the root element:

• HTML attributes such as role and id.
• aria-* attributes. An aria-current you pass wins over the one derived from the selected state.
• data-* attributes.
• class.
• style.

The component writes data-density, data-align, data-interactive, data-selected, data-disabled, data-highlighted, data-inert, aria-disabled, and the derived aria-selected / aria-current. Those are not overridden by an attribute of the same name passed in.