DocsComponents

List

Rows of related content with icons, captions, and secondary text.

Selected: Inbox

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/list.json

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

Use caption, legend, and icons for content rows. For actions or navigation, itemContent accepts a native button or router link, preserving keyboard access. List supplies selectable and ripple to its rows; subheaders, dividers, and ListCheckbox are also included.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

List and ListItem do not store a selected item. Use your own selection state and item handlers. selectable enables interaction feedback; ripple enables pointer ink feedback.

ListCheckbox is controlled through checked and onChange. Update the checked prop with the callback’s next boolean.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`List`

Property	Type	Default
`ripple`	`boolean`	`false`
`selectable`	`boolean`	`false`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Also inherits ComponentPropsWithRef<'ul'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Additional defaults on inherited props: className = ''.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListItem`

Property	Type	Default
`avatar`	`ReactNode`	`—`
`caption`	`ReactNode`	`—`
`className`	`string`	`''`
`disabled`	`boolean`	`false`
`itemContent`	`ReactNode`	`—`
`leftActions`	`ReactNode[]`	`—`
`leftIcon`	`ReactNode`	`—`
`legend`	`ReactNode`	`—`
`rightActions`	`ReactNode[]`	`—`
`rightIcon`	`ReactNode`	`—`
`selectable`	`boolean`	`—`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`ripple`	`boolean`	`false`
`rippleCentered`	`boolean`	`false`
`rippleClassName`	`string`	`—`
`rippleMultiple`	`boolean`	`—`
`rippleSpread`	`number`	`—`
`to`	`string`	`—`

Callbacks

Property	Type	Default
`onRippleEnded`	`TransitionEventHandler<HTMLSpanElement>`	`—`

Also inherits ComponentPropsWithRef<'li'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListCheckbox`

Property	Type	Default
`caption`	`ReactNode`	`—`
`checked`	`boolean`	`false`
`disabled`	`boolean`	`false`
`legend`	`ReactNode`	`—`
`name`	`string`	`—`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Callbacks

Property	Type	Default
`onBlur`	`CheckboxProps['onBlur']`	`—`
`onChange`	`(checked: boolean, event: React.MouseEvent<HTMLInputElement>) => void`	`—`
`onFocus`	`CheckboxProps['onFocus']`	`—`

Also inherits Omit<ComponentPropsWithRef<'li'>, 'onBlur' | 'onChange' | 'onFocus'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListDivider`

Property	Type	Default
`inset`	`boolean`	`false`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Also inherits ComponentPropsWithRef<'hr'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListItemAction`

Property	Type	Default
`action`Required	`ReactElement<Pick<HTMLAttributes<HTMLElement>, 'onClick' \| 'onMouseDown'>>`	`—`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListItemActions`

Property	Type	Default
`children`	`ReactNode`	`—`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`type`Required	`'left' \| 'right'`	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListItemContent`

Property	Type	Default
`caption`	`ReactNode`	`—`
`legend`	`ReactNode`	`—`
`classNames`	`ListTheme & { auto?: string; normal?: string }` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme & { auto?: string; normal?: string }` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`type`	`'auto' \| 'normal' \| 'large'`	`—`

Also inherits ComponentPropsWithRef<'span'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

auto
checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
normal
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListItemLayout`

Property	Type	Default
`avatar`	`ReactNode`	`—`
`caption`	`ReactNode`	`—`
`className`	`string`	`—`
`disabled`	`boolean`	`false`
`itemContent`	`ReactNode`	`—`
`leftActions`	`ReactNode[]`	`[]`
`leftIcon`	`ReactNode`	`—`
`legend`	`ReactNode`	`—`
`rightActions`	`ReactNode[]`	`[]`
`rightIcon`	`ReactNode`	`—`
`selectable`	`boolean`	`false`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListItemText`

Property	Type	Default
`primary`	`boolean`	`false`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`ListSubHeader`

Property	Type	Default
`caption`	`ReactNode`	`—`
`classNames`	`ListTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ListTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Also inherits ComponentPropsWithRef<'h5'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Additional defaults on inherited props: className = ''.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

checkbox
checkboxItem
disabled
divider
inset
item
itemAction
itemContentRoot
itemText
large
left
list
listItem
primary
right
ripple
selectable
subheader

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/list.

ListProps

tsx

interface ListProps extends ComponentPropsWithRef<'ul'> {
  ripple?: boolean;
  selectable?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
}

ListItemProps

tsx

interface ListItemProps extends ComponentPropsWithRef<'li'>, ListItemLayoutProps, RippleProps {
  to?: string;
}

ListCheckboxProps

tsx

interface ListCheckboxProps extends Omit<ComponentPropsWithRef<'li'>, 'onBlur' | 'onChange' | 'onFocus'> {
  caption?: ReactNode;
  checked?: boolean;
  disabled?: boolean;
  legend?: ReactNode;
  name?: string;
  onBlur?: CheckboxProps['onBlur'];
  onChange?: CheckboxProps['onChange'];
  onFocus?: CheckboxProps['onFocus'];
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
}

ListDividerProps

tsx

interface ListDividerProps extends ComponentPropsWithRef<'hr'> {
  inset?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
}

ListItemActionProps

tsx

interface ListItemActionProps {
  action: ReactElement<Pick<HTMLAttributes<HTMLElement>, 'onClick' | 'onMouseDown'>>;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
}

ListItemActionsProps

tsx

interface ListItemActionsProps {
  children?: ReactNode;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
  type: 'left' | 'right';
}

ListItemContentProps

tsx

interface ListItemContentProps extends ComponentPropsWithRef<'span'> {
  caption?: ReactNode;
  legend?: ReactNode;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme & { auto?: string; normal?: string };
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme & { auto?: string; normal?: string };
  type?: 'auto' | 'normal' | 'large';
}

ListItemLayoutProps

tsx

interface ListItemLayoutProps {
  avatar?: ReactNode;
  caption?: ReactNode;
  className?: string;
  disabled?: boolean;
  itemContent?: ReactNode;
  leftActions?: ReactNode[];
  leftIcon?: ReactNode;
  legend?: ReactNode;
  rightActions?: ReactNode[];
  rightIcon?: ReactNode;
  selectable?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
}

ListItemTextProps

tsx

interface ListItemTextProps extends ComponentPropsWithRef<'span'> {
  primary?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
}

ListSubHeaderProps

tsx

interface ListSubHeaderProps extends ComponentPropsWithRef<'h5'> {
  caption?: ReactNode;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ListTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ListTheme;
}

Material guidelines

Keep row content consistent and align icons, avatars, and text to common keylines. Use secondary text only when it helps distinguish items.
The primary action occupies the row. Put separate secondary actions in their own controls, and provide focus and ripple feedback for interactive rows.
Navigation rows use 14px medium labels; ordinary content lists use their own body-text metrics. Avoid treating every informational row as an action.

Material Design 1: Lists