Presentational row with leading, secondary, trailing, density, and muted or accent variants. Includes ListItemLabel for menu and nav section headings, and ListItemNest for indented child groups with an optional guide line. Option List and Contents Nav compose these for selectable options and outlines.
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)
npx --yes -p github:itsvigneshv/default-file-ui#main df-ui add list-item
Default, highlighted, selected, and disabled rows.
Density steps sm, md, and lg. md matches Option List rows. Override further with chrome padding and fontSize props.
Leading, secondary, trailing, and stacked layout.
Same pattern as the catalogue On this page rail. Muted rows with asChild links, md for top-level headings, sm for nested entries, and ListItemNest for the child group guide line. Prefer Contents Nav for a ready outline.
Padding, gap, type size, radius, and fills via chrome props. Values write --df-list-item-* on the row. Prefer kit tokens. List Item paints fills only; use radius to shape the fill.
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.
Presentational row for menus, pickers, and 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 and Contents Nav wrap List Item for selection and outlines. Use asChild to paint the row onto your own link. Chrome props set --df-list-item-* variables so padding, gap, type size, radius, and fills can be overridden per row.
Row chrome, density, and presentational state.
| Prop | Type | Default | Notes |
|---|---|---|---|
| size | "sm" | "md" | "lg" | "md" | Density and type size. md matches Option List rows. sm is compact for nested nav. lg is roomier. 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. 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. |
| open | boolean | false | Open state for submenu-style rows. |
| leading | "checkbox" | "check" | ReactNode | false | - | Leading slot. Pass an icon, "checkbox" or "check" for selection marks, or false to omit. |
| secondary | ReactNode | - | Supporting copy beside or under the label. |
| layout | "inline" | "stacked" | "inline" | inline places secondary beside the label. stacked places it underneath. |
| trailing | ReactNode | - | End slot for badges, chevrons, or actions. |
| indicator | boolean | false | Show a trailing check when selected. |
| 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. 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) or calc(2 * var(--spacing-unit)). Size and variant still supply defaults when a prop is omitted. OptionListItem and SelectItem forward the same props.
| 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 | - | Space between leading, label, and trailing 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. |
| 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. |
| selectedBackground | string | - | Selected fill. Also updates the selected hover fill. Sets --df-list-item-selected-bg and --df-list-item-selected-hover-bg. |
| radius | string | - | Corner radius of the row fill. Prefer radius tokens such as var(--radius-md) or var(--radius-2xl). List Item has no border chrome. Sets --df-list-item-radius. |
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. |
Indented group for nested rows. Optional guide line via line. Chrome props write --df-list-item-nest-* on the host. Contents Nav uses this for toc children.
| 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 | - | Slot gap. Set by the gap prop. |
| --df-list-item-font-size | CSS length | - | Label type size. Set by the fontSize 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-selected-bg | CSS color | - | Selected fill. Set by the selectedBackground 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. |