Item
A flexible composition primitive for compact product content, media, metadata, and independent actions.
Overview and decision boundary
Use Item to compose a compact content unit with optional media, metadata, and actions without forcing list semantics or interaction.
Do not use for Field-controlled form options, selectable listboxes, data tables, or a product-specific activity feed.
import { FileText } from "@nerio-ui/adapters/icons";import { Item, ItemActions, ItemContent, ItemDescription, ItemMedia, ItemTitle } from "@nerio-ui/ui";import { Button } from "@nerio-ui/ui/client";<Item variant="outline"> <ItemMedia variant="icon"><FileText /></ItemMedia> <ItemContent> <ItemTitle>Research brief</ItemTitle> <ItemDescription>Updated today · 12 collaborators have access.</ItemDescription> </ItemContent> <ItemActions><Button size="sm" variant="secondary">Open</Button></ItemActions></Item>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 itemimport { Item, ItemActions, ItemContent, ItemMedia, ItemTitle } from '@nerio-ui/ui';Usage
import { Item, ItemActions, ItemContent, ItemMedia, ItemTitle } from '@nerio-ui/ui';<Item render={<a href="/settings" />}> <ItemMedia variant="icon">...</ItemMedia> <ItemContent><ItemTitle>Workspace settings</ItemTitle></ItemContent> <ItemActions>...</ItemActions></Item>Variants
Anatomy
ItemGroup
└── Item
├── ItemHeader
├── ItemMedia
├── ItemContent
│ ├── ItemTitle
│ └── ItemDescription
├── ItemActions
└── ItemFooterStates
Motion
- hover and press only on native interactive rendered roots
Accessibility
- Item has no implicit role; choose div, li, a, or button according to context.
- Use render with a native anchor or button only when the full item has one clear interaction.
- A ref already attached to the render element is composed with the forwarded Item or ItemGroup ref; callback and object refs are both supported.
- Do not nest independent actions inside a fully clickable Item.
- Static Items are not focusable; interactive rendered roots keep native keyboard and focus behavior.
- ItemSeparator is decorative by default.
API
| Part | API | Purpose |
|---|---|---|
Item | variant | size | render | Root composition; render a native interactive element when needed. Existing render refs compose with the forwarded ref. |
ItemMedia | default | icon | image | Supports visual media. Compose Avatar directly instead of adding an avatar mode. |
ItemGroup / ItemSeparator | children | Groups related items without list semantics or automatic dividers. |
Content slots | ItemContent | ItemTitle | ItemDescription | ItemActions | ItemHeader | ItemFooter | Independent layout regions with native props, refs, className, and stable data slots. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | item installs Item with the Separator registry dependency. |
Base UI | No interactive primitive required. |
Registry dependencies | separator |
Package dependencies | @nerio-ui/adapters, clsx, react |
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 Item to compose a compact content unit with optional media, metadata, and actions without forcing list semantics or interaction.
Do / do not
Use Item
For settings rows, integrations, results, files, people, and compact content inside overlays.
Do not use Item
For form-control labels, selectable listbox behavior, data tables, or a product-specific activity feed.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-item-gap | Public customization point for this component contract. |
--n-item-padding | Public customization point for this component contract. |
--n-item-radius | Public customization point for this component contract. |
--n-item-background-hover | Public customization point for this component contract. |
--n-item-background-selected | Public customization point for this component contract. |
--n-item-border | Public customization point for this component contract. |
--n-item-media-size-md | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |