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 exec 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
| Variant | Purpose |
|---|---|
plain | Plain is part of the public component contract. |
outline | Outline is part of the public component contract. |
soft | Soft is part of the public component contract. |
sm | Compact size for dense layouts and inline use. |
md | Default size for most product surfaces. |
lg | Larger size for prominent local actions. |
default-media | Default Media is part of the public component contract. |
icon-media | Icon Media is part of the public component contract. |
image-media | Image Media is part of the public component contract. |
Anatomy
| Slot | Purpose |
|---|---|
item | Generic root with no implicit role. |
item-group | Optional full-width grouping container. |
item-separator | Item Separator slot exposed through data-slot="item-separator". |
item-media | Optional leading custom, icon, or image media. |
item-content | Flexible main region with safe minimum inline size. |
item-title | Item Title slot exposed through data-slot="item-title". |
item-description | Item Description slot exposed through data-slot="item-description". |
item-actions | Independent trailing controls or compact metadata. |
item-header | Item Header slot exposed through data-slot="item-header". |
item-footer | Item Footer slot exposed through data-slot="item-footer". |
States
| State | Purpose |
|---|---|
Selected | Consumer-supplied data-selected uses the semantic selected surface. |
Disabled | aria-disabled reduces emphasis; consumers prevent activation for native links. |
Loading | data-loading suppresses pointer interaction while composed Skeleton or Spinner preserves layout. |
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.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
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-group-outline-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. |