ListItem

ListItem provides a rich list-entry layout. It is interactive by default and renders as a button, or as an anchor when href is set. Set interactive="false" for a passive information row or a row whose nested control owns the interaction; passive items render as div elements without button, link, focus, state-layer, or press behavior. Any href is ignored while the item is passive.

ListItem automatically participates in the List Grouping CSS utility, which can also group other elements and components.

Sizes

size selects row geometry independently of appearance. It inherits from listItemDefaults.size or provideListItemDefaults({ size }), with medium (56px) as the library default. Helpers merge fields reactively; undefined restores inheritance. Button size defaults do not control list rows.

Size	Minimum height	Block padding	Inline padding	Icon gap	Icon size
extra-small	36px	6px	12px	8px	20px
small	48px	6px	16px	12px	24px
medium	56px	6px	16px	20px	24px
large	64px	8px	22px	20px	24px
extra-large	80px	10px	24px	24px	28px

Public tokens override preset values: --md-item-min-height, --md-item-padding-block, --md-item-padding-inline, --md-item-gap, --md-item-content-gap, and --md-item-icon-size. Set them on an ancestor or on the component root; root values take precedence over inherited values. Components do not assign these public geometry tokens themselves.

The table shows density 0. The inherited --md-density token reduces minimum height and vertical padding, without changing text, icons or horizontal spacing. Public dimension tokens take precedence. Presets specify minimum heights, so descriptions and multiline titles can grow the row. See Density.

Examples

Default

Compositions

M3 Library Overview Open the Button docs page.→

Vue Router

When ListItem is acting as navigation, use RouterLink custom and feed its href and navigate into the component.

person Profile Manage your account details.chevron_rightshield Security Passwords, passkeys, and sign-in alerts.chevron_right

Current route: /account/profile

Appearance

appearance="standard" is the default: a fixed whole-row active indicator, compact corners, and no expanding highlight or press shape morph. appearance="expressive" retains the expanding indicator and press morph. Appearance does not change button/link/presentation semantics, slots, or layout tokens. Set listItemDefaults.appearance in M3VuePlugin for an application default, or call provideListItemDefaults({ appearance: 'expressive' }) for a subtree. An explicit appearance prop takes precedence.

standard

expressive

Set appearance="expressive" on existing items to retain the previous appearance. The shape prop controls the expressive shape; standard uses --md-shape-compact. --md-item-indicator-shape can customize the indicator in either appearance.

Use MenuItem for menu commands. ListItem remains a general list entry. See Styling for appearance and density choices.

Selection Controls in List Items

CheckBox, Radio, and Switch can appear inside a list item as state indicators. In that layout the row is usually the larger, easier target, while the selection control only communicates the current state.

Use the control's presentation prop for this case. Presentation mode keeps the Material 3 visual state, but removes the nested native input, hides the visual control from assistive technology, and disables the control's own state-layer effect. The parent row must provide the accessible name, role, checked state, disabled state, and interaction feedback.

Pattern

Accessibility Rules

• Keep one interactive target per row. The row is the control; the visual CheckBox, Radio, or Switch is not another focusable element.
• Put the accessible name on the row, usually through visible title text.
• Set aria-checked on the row and keep it synchronized with the visual control's checked state.
• Use the matching role: checkbox for independent selections, radio for a single choice within a set, and switch for immediate on/off settings.
• Wrap related radio rows in a radiogroup with an accessible name.
• For radio groups that need native radio keyboard behavior, keep native radio inputs or add arrow-key navigation in the parent group.
• When a row is disabled, disable the row and pass disabled to the presentation control so the visual state matches the interaction state.

When Not to Use Presentation

Do not use presentation for a standalone control. A standalone CheckBox, Radio, or Switch should keep its native input so forms, keyboard interaction, focus indication, and assistive technology work without extra code.

Also avoid rendering a disabled visual control inside an enabled row. That communicates that the visible control is unavailable while the row still changes state, which is confusing.

Reference

Anatomy

Highlight

Element	Part	Selector
<component>	root	[data-scope="item"][data-part="root"] left_clickLMBCopy
<Icon>	leadingconditional	[data-scope="item"][data-part="leading"] left_clickLMBCopy
<span>	main	[data-scope="item"][data-part="main"] left_clickLMBCopy
<span>	headerconditional	[data-scope="item"][data-part="header"] left_clickLMBCopy
<span>	titleconditional	[data-scope="item"][data-part="title"] left_clickLMBCopy
<span>	descriptionconditional	[data-scope="item"][data-part="description"] left_clickLMBCopy
<span>	footerconditional	[data-scope="item"][data-part="footer"] left_clickLMBCopy
<Icon>	trailingconditional	[data-scope="item"][data-part="trailing"] left_clickLMBCopy

Props

Name	Description	Default	Control
shapeOptional	The shape of the button. M3Shape | undefined	undefined	-
hrefOptional	The href attribute. If provided, the button will be rendered as an anchor element. string | undefined	undefined
leadingIconOptional	Name of the leading icon. string | undefined	undefined
trailingIconOptional	Name of the trailing icon. string | undefined	undefined
disabledOptional	Whether the button is disabled. boolean | undefined	undefined
sizeOptional	Row geometry preset. Public item tokens override individual dimensions. ListItemSize | undefined	undefined	-
appearanceOptional	Standard fixed highlight or expressive expanding indicator and press morph. standardexpressive	undefined	checkstandardexpressive
interactiveOptional	Whether the whole item is an interactive action or link. boolean | undefined	true	check
activeOptional	Highlight the item as active/selected. boolean | undefined	false
titleOptional	Fallback title when default slot is not provided. string | undefined	undefined
descriptionOptional	Fallback description when description slot is not provided. string | undefined	undefined

Slots6

Name	Parameters	Description
header	-	Optional content above the main row.
leading	-	Optional leading content.
default	-	Main title content.
description	-	Optional description below the title.
trailing	-	Optional trailing content.
footer	-	Optional content below the main row.

Styling20

Preview

Token	Description
--md-item-active-icon-colorColor Fallbackvar(--md-sys-color-on-secondary-container)	Controls active icon color.
--md-item-active-indicator-colorColor Fallbackvar(--md-sys-color-secondary-container)	Controls active indicator color.
--md-item-active-label-colorColor Fallbackvar(--md-sys-color-on-secondary-container)	Controls active label color.
--md-item-active-state-layer-colorState Fallbackvar(--md-sys-color-on-secondary-container)	Controls active state layer color.
--md-item-content-gapLayout Fallback--dp(2)	Controls content gap.
--md-item-footer-colorColor Fallbackvar(--md-sys-color-on-surface-variant)	Controls footer color.
--md-item-gapLayout Fallback--dp(12)	Controls gap.
--md-item-header-colorColor Fallbackvar(--md-sys-color-on-surface-variant)	Controls header color.
--md-item-icon-sizeLayout FallbackSize, typography, density and icon scale (default medium reference: 24dp)	Controls icon size.
--md-item-inactive-icon-colorColor Fallbackvar(--md-color-on-container)	Controls inactive icon color.
--md-item-inactive-label-colorColor Fallbackvar(--md-color-on-container)	Controls inactive label color.
--md-item-inactive-state-layer-colorState Fallbackvar(--md-color-on-container)	Controls inactive state layer color.
--md-item-indicator-collapsed-visual-widthLayout Fallback--dp(12)	Controls indicator collapsed visual width.
--md-item-indicator-shapeShape Fallbackvar(--md-shape-indicator)	Controls indicator shape.
--md-item-main-padding-blockLayout Fallback--dp(8)	Controls main padding block.
--md-item-main-padding-inlineLayout Fallback--dp(12)	Controls main padding inline.
--md-item-min-heightLayout Fallback--dp(56)	Controls min height.
--md-item-motionMotion Fallbackvar(--md-easing-spatial)	Controls motion.
--md-item-padding-blockLayout Fallback--dp(8)	Controls padding block.
--md-item-padding-inlineLayout Fallback--dp(8)	Controls padding inline.