List
Lists present simple structured items with descriptions, metadata, and native links.
Overview and decision boundary
Use List to present short structured items that are not tabular data and do not need selection behavior.
Do not use List for DataGrid, command palette, sidebar navigation, or selectable listbox patterns.
Preview
- TokensCSS variable foundation for themes, modes, and density.
- ComponentsComposable Core primitives installed as source.
- Install tokens
- Register Tailwind source
import * as React from 'react';import { List } from '@nerio-ui/ui';const AppLink = React.forwardRef<HTMLAnchorElement, React.AnchorHTMLAttributes<HTMLAnchorElement>>(function AppLink(props, ref) { return <a ref={ref} data-router-link="" {...props} />;});<List items={[{ id: 'tokens', title: 'Tokens', description: 'CSS variable foundation for themes, modes, and density.', href: '/docs/foundations/tokens', render: <AppLink href="#" /> }, { id: 'components', title: 'Components', description: 'Composable Core primitives installed as source.', href: '/docs/components/button' }]} />Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm dlx nerio add listimport * as React from 'react';import { List } from '@nerio-ui/ui';Usage
import * as React from 'react';import { List } from '@nerio-ui/ui';const AppLink = React.forwardRef<HTMLAnchorElement, React.AnchorHTMLAttributes<HTMLAnchorElement>>(function AppLink(props, ref) { return <a ref={ref} data-router-link="" {...props} />;});<List items={[{ id: 'tokens', title: 'Tokens', description: 'CSS variable foundation for themes, modes, and density.', href: '/docs/foundations/tokens', render: <AppLink href="#" /> }, { id: 'components', title: 'Components', description: 'Composable Core primitives installed as source.', href: '/docs/components/button' }]} />Variants
| Variant | Purpose |
|---|---|
unordered | Unordered is part of the public component contract. |
ordered | Ordered is part of the public component contract. |
Anatomy
| Slot | Purpose |
|---|---|
root | Semantic ul by default or ol when ordered is true. |
item | One structured list item. |
body | Body slot exposed through data-slot="body". |
link | Native anchor wrapper when an item has href. |
leading | Leading slot exposed through data-slot="leading". |
content | Content slot exposed through data-slot="content". |
title | Primary item label. |
description | Optional supporting item copy. |
trailing | Trailing slot exposed through data-slot="trailing". |
meta | Optional compact metadata in the trailing slot. |
States
| State | Purpose |
|---|---|
Static | Items without href render as non-interactive content. |
Linked | Items with href render native anchors. |
Focus | Linked items use the shared Nerio focus ring. |
Motion
- hover
- focus
Accessibility
- Uses semantic ul by default and semantic ol when ordered is true.
- Items with href render native anchors instead of fake interactive containers.
- Optional description and metadata remain in the natural reading order.
- linkProps can extend class, events, target, rel, aria, and data attributes; item.href and the internal data-slot remain protected.
- Use render for a custom router link element; List forwards the canonical href, merged class, accessible props, and link data-slot without depending on a router package.
- Do not use List for selectable listbox, command menu, or data table behavior.
API
| Prop | Purpose |
|---|---|
items | Array of title, description, meta, href, leading, and trailing values. |
ordered | Renders an ol when sequence matters; otherwise renders a ul. |
linkProps | Extends link behavior but cannot replace the canonical item.href or internal link anatomy. |
render | Optional router link element that receives the canonical href, class, accessible props, and link data-slot. |
className | Extends the list root without replacing tokenized defaults. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | list installs 6 source files into the configured components directory. |
Base UI | No interactive primitive required. |
Registry dependencies | None. |
Package dependencies | clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use List to present short structured items that are not tabular data and do not need selection behavior.
Do / do not
Do
Use for docs links, settings summaries, compact resources, and simple object lists.
Do not
Do not use List for DataGrid, command palette, sidebar navigation, or selectable listbox patterns.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-list-gap | Public customization point for this component contract. |
--n-list-item-padding | Public customization point for this component contract. |
--n-list-item-gap | Public customization point for this component contract. |
--n-list-item-radius | Public customization point for this component contract. |
--n-list-item-background | Public customization point for this component contract. |
--n-list-item-background-hover | Public customization point for this component contract. |
--n-list-item-border | Public customization point for this component contract. |
--n-list-item-border-hover | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |