Configurable row with leading, secondary, trailing, density, muted or accent variants, readOnly presentational rows, and as="button" or asChild link hosts. Includes ListItemLabel for menu and nav section headings, and ListItemNest for indented child groups with an optional guide line. Option List, Select, Combobox, Tag Input, Contents Nav, Sidebar, and Dropdown Menu compose these for selectable options, outlines, and app nav.
Also known as: list row, menu item, nav item, option row, line item
Install with the CLI, or copy the component source into your project.
Add list-item (npm)
1npx --yes -p @default-file/ui df-ui add list-item
Default, highlighted, selected, and disabled rows.
Density steps xs, sm, md, and lg. xs is nest and TOC child. sm is TOC parent. md matches Option List and the left index. Override further with chrome padding and fontSize props.
Leading, secondary, trailing, and stacked layout. Icons use the default icon track. Avatar and other non-icon marks use leadingFit content.
OptionListItem is List Item. Wrap a parent row in OptionListSubmenu so hover opens OptionListSubContent. Nest again for deeper levels. Badge plus chevron marks parents. Prefer this over inventing a separate hover menu on bare List Item.
Three-column text row for scales and metrics. Leading and trailing hug the edges; the main specimen stays centered in the row. Row height follows the specimen. Use chrome props for padding, fill, stroke, and type.
Same pattern as the catalogue On this page rail. Muted rows with asChild links, sm for TOC parents, xs for nested entries, and ListItemNest for the child group guide line. Prefer Contents Nav for a ready outline.
Padding, gap, type (size, family, weight, color), radius, fills, and stroke via chrome props. Values write --df-list-item-* on the row. Prefer kit tokens. The same props forward through Option List, Select, and Contents Nav itemChrome.
asChild paints the List Item look onto your own link. The <a> (or Next.js Link) is the clickable row, so navigation stays native.
ListItemLabel headings for groups. menu matches Option List. nav matches catalogue sidebar sections.
Configurable row for menus, pickers, TOC, and app navigation. Compose leading, secondary, and trailing slots. Pair with ListItemLabel for section headings and ListItemNest for indented child groups with an optional guide line. Option List, Select, Combobox, Tag Input, Contents Nav, Sidebar, and Dropdown Menu compose List Item. Use as="button" for in-page actions. Use asChild to paint the row onto a link. Pass itemChrome on composer roots for shared defaults, or set chrome props on each row. Chrome props set --df-list-item-* variables so padding, gap, type (size, family, weight, color), radius, fills, and stroke can be overridden per row.
Row chrome, density, host element, and presentational state.
| Prop | Type | Default | Notes |
|---|---|---|---|
| size | "xs" | "sm" | "md" | "lg" | "md" | Density and type size. xs is nest and TOC child (text-11). sm is TOC parent (text-13). md matches Option List and the left index (text-sm). lg is roomier. For muted, each size has its own density recipe. Override further with padding and fontSize props. |
| variant | "accent" | "muted" | "accent" | accent uses picker hover and selected fills. muted uses quiet nav fills for catalogue and TOC rows. Density for muted is per size. Override fills with background, hoverBackground, and selectedBackground. |
| selected | boolean | false | Selected or current row appearance. |
| highlighted | boolean | false | Hover or keyboard highlight without selecting. |
| disabled | boolean | false | Non-interactive row. Sets aria-disabled and dims the row. On as="button", also sets the native disabled attribute. |
| readOnly | boolean | false | Presentational row for reading only. Keeps size, variant, and selected appearance with no hover, press, focus, or activation. Distinct from disabled, which dims the row. Option List, Select, Dropdown Menu, Contents Nav, and Combobox options skip or forward readOnly through the same contract. |
| open | boolean | false | Open state for submenu-style rows. Sets data-open. Independent of selected, which sets data-state. |
| leading | "checkbox" | "check" | ReactNode | false | - | Leading slot. Pass an icon, "checkbox" or "check" for selection marks, or false to omit. Icons use the icon track by default. For Avatar or other non-icon marks, set leadingFit to content. In columns layout, pass text; the slot hugs content. Set aria-hidden on decorative icons. |
| leadingFit | "icon" | "content" | "icon" | Track size for custom leading nodes. icon keeps the mark box used by row icons. content sizes the track to the node. Use content for Avatar, media, or text marks. Ignored for checkbox and check. Stacked rows with content center the leading, label stack, and trailing as one group. |
| secondary | ReactNode | - | Supporting copy beside or under the label. Long title and secondary text truncate with an ellipsis when the row is narrower than the copy. |
| layout | "inline" | "stacked" | "columns" | "inline" | inline places secondary beside the label. stacked places it underneath. columns is a three-column text row: leading, main label, and trailing. The main label stays horizontally centered in the row. Leading and trailing hug their tracks. Height follows content. columns does not require secondary. |
| trailing | ReactNode | - | End slot for badges, chevrons, measures, or actions. Stays end-aligned with margin-inline-start auto when the row spans its parent. For nested menu affordances, pass ListItemSubmenuChevron so size matches the indicator slot. When List Item is an OptionListTrigger render host, set OptionList width fill (or a fixed length) so the row has width to push against. In columns layout, use for end-aligned text such as a size value. |
| indicator | boolean | false | Reserve an end check slot. The check shows when selected. The slot stays end-aligned with auto space before it; --df-list-item-gap is the minimum space from the label. Long labels truncate. |
| as | "div" | "button" | "div" | Native host when asChild is false. Use button for clickable rows without navigation. Ignored when asChild is true. |
| asChild | boolean | false | When true, List Item does not render its own wrapper. Pass one child element (usually a link). That element becomes the clickable row and keeps its own href or routing. Prefer this over wrapping List Item in a separate link. The child text is the label. |
| children | ReactNode | - | Label text by default. With asChild, pass a single element such as <a> or <Link> instead. |
| className | string | - | Additional styles on the host. |
String props write --df-list-item-* on the host. Prefer token expressions such as var(--muted), var(--border-width-hairline), or calc(2 * var(--spacing-unit)). Size and variant still supply defaults when a prop is omitted. OptionListItem, SelectItem, Combobox, Tag Input, and ContentsNavItem forward the same props. Root itemChrome sets defaults for every row; per-item props win.
| Prop | Type | Default | Notes |
|---|---|---|---|
| padding | string | - | Padding on all sides. Sets each --df-list-item-padding-* side. |
| paddingX | string | - | Horizontal padding. Sets --df-list-item-padding-left and --df-list-item-padding-right. Overrides padding on those sides. |
| paddingY | string | - | Vertical padding. Sets --df-list-item-padding-top and --df-list-item-padding-bottom. Overrides padding on those sides. |
| paddingTop | string | - | Top padding. Sets --df-list-item-padding-top and wins over paddingY and padding. |
| paddingRight | string | - | Right padding. Sets --df-list-item-padding-right and wins over paddingX and padding. |
| paddingBottom | string | - | Bottom padding. Sets --df-list-item-padding-bottom and wins over paddingY and padding. |
| paddingLeft | string | - | Left padding. Sets --df-list-item-padding-left and wins over paddingX and padding. |
| gap | string | - | Minimum space between leading, label, trailing, and indicator slots. Sets --df-list-item-gap. |
| fontSize | string | - | Label type size. Prefer type tokens such as var(--df-text-11). Sets --df-list-item-font-size. |
| fontFamily | string | - | Label font family. Prefer family tokens such as var(--df-font-sans) or var(--df-font-mono). Sets --df-list-item-font-family. |
| fontWeight | string | - | Label font weight. Prefer weight tokens such as var(--df-font-weight-semibold). Sets --df-list-item-font-weight. Accent titles default to medium when omitted; muted defaults to normal. |
| background | string | - | Resting fill. Sets --df-list-item-bg. |
| foreground | string | - | Resting label color. Sets --df-list-item-fg. |
| hoverBackground | string | - | Hover, highlight, and focus fill. Sets --df-list-item-hover-bg. |
| hoverForeground | string | - | Hover, highlight, and focus label color. Sets --df-list-item-hover-fg. |
| selectedBackground | string | - | Selected fill. Also sets selected hover fill unless selectedHoverBackground is passed. Sets --df-list-item-selected-bg and --df-list-item-selected-hover-bg. |
| selectedForeground | string | - | Selected label color. Sets --df-list-item-selected-fg. |
| selectedHoverBackground | string | - | Selected row hover fill. Sets --df-list-item-selected-hover-bg. |
| activeBackground | string | - | Pressed fill. Sets --df-list-item-active-bg. |
| radius | string | - | Corner radius of the row fill and stroke. Prefer radius tokens such as var(--radius-md) or var(--radius-2xl). Sets --df-list-item-radius. |
| borderWidth | string | - | Stroke width. Prefer border tokens such as var(--border-width-hairline). Default 0 (no stroke). Sets --df-list-item-border-width. |
| borderColor | string | - | Stroke color. Prefer var(--border) or other color tokens. Sets --df-list-item-border-color. |
| borderStyle | string | - | Stroke style such as solid or dashed. Default solid. Sets --df-list-item-border-style. |
Section heading above a group of rows (data-df list-item-section). OptionListLabel and SelectLabel use the menu variant.
| Prop | Type | Default | Notes |
|---|---|---|---|
| variant | "menu" | "nav" | "menu" | menu is the quiet picker group title (Option List). nav is the uppercase mono catalogue section title. |
| children | ReactNode | - | Section title text. |
| className | string | - | Additional styles. |
Nested menu affordance for the trailing slot. Uses the same size box as the indicator check and muted foreground. Dropdown Menu injects it when a submenu trigger has no custom trailing. Pass it from Option List and Sidebar rows that open nested panels.
| Prop | Type | Default | Notes |
|---|---|---|---|
| className | string | - | Additional styles on the chevron host. |
Indented group for nested rows. Optional guide line via line. Chrome props write --df-list-item-nest-* on the host. Provides nest scope so ContentsNavItem defaults to nestItemSize inside the group.
| Prop | Type | Default | Notes |
|---|---|---|---|
| line | boolean | true | When true, paints the nest guide line. When false, keeps indent without a line. |
| indent | string | - | Outer inset before the nest group. Prefer spacing tokens. Sets --df-list-item-nest-indent. |
| pad | string | - | Inner pad after the guide line. Prefer spacing tokens. Sets --df-list-item-nest-pad. |
| gap | string | - | Gap between nested rows. Sets --df-list-item-nest-gap. |
| lineWidth | string | - | Guide line thickness. Prefer var(--border-width-hairline). Sets --df-list-item-nest-line-width. |
| lineColor | string | - | Guide line color. Prefer var(--border). Sets --df-list-item-nest-line-color. |
| children | ReactNode | - | Nested List Item rows. |
| className | string | - | Additional styles. |
Theme defaults live on :root. Override these globally or on a local host.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-list-item-padding-top | CSS length | - | Top padding. Set by padding, paddingY, or paddingTop. |
| --df-list-item-padding-right | CSS length | - | Right padding. Set by padding, paddingX, or paddingRight. |
| --df-list-item-padding-bottom | CSS length | - | Bottom padding. Set by padding, paddingY, or paddingBottom. |
| --df-list-item-padding-left | CSS length | - | Left padding. Set by padding, paddingX, or paddingLeft. |
| --df-list-item-gap | CSS length | - | Minimum space between leading, label, trailing, and indicator slots. Set by the gap prop. |
| --df-list-item-indicator-size | CSS length | - | Width and height of the end check slot when indicator is on. |
| --df-list-item-font-size | CSS length | - | Label type size. Set by data-size recipes, or by the fontSize chrome prop. |
| --df-list-item-radius | CSS length | - | Row corner radius. Set by the radius prop. |
| --df-list-item-bg | CSS color | - | Resting fill. Set by the background prop. |
| --df-list-item-fg | CSS color | - | Resting label color. Set by the foreground prop. |
| --df-list-item-hover-bg | CSS color | - | Hover and highlight fill. Set by the hoverBackground prop. |
| --df-list-item-hover-fg | CSS color | - | Hover and highlight label color. Set by the hoverForeground prop. |
| --df-list-item-selected-bg | CSS color | - | Selected fill. Set by the selectedBackground prop. |
| --df-list-item-selected-fg | CSS color | - | Selected label color. Set by the selectedForeground prop. |
| --df-list-item-selected-hover-bg | CSS color | - | Selected hover fill. Set by selectedHoverBackground or selectedBackground. |
| --df-list-item-active-bg | CSS color | - | Pressed fill. Set by the activeBackground prop. |
| --accent | CSS color | - | Default accent hover and selected recipe. |
| --muted | CSS color | - | Default muted selected and hover recipe. |
| --muted-foreground | CSS color | - | Default muted resting label color. |
| --df-list-item-nest-indent | CSS length | - | Outer nest inset. Set by ListItemNest indent. |
| --df-list-item-nest-pad | CSS length | - | Inner nest pad. Set by ListItemNest pad. |
| --df-list-item-nest-gap | CSS length | - | Gap between nested rows. Set by ListItemNest gap. |
| --df-list-item-nest-line-width | CSS length | - | Nest guide thickness. Set by ListItemNest lineWidth. |
| --df-list-item-nest-line-color | CSS color | - | Nest guide color. Set by ListItemNest lineColor. |