Data Display & Media
Item
A row that shows one thing — an icon, avatar or image, a title, a description and actions — on its own or in a list, and opens it when clicked.
An item is one row: a policy, a person, a file, a setting. It sets out a picture, a title and a line about it, with actions at the end, and lines up with the items around it. For rows of data with columns, use the table; for a block with its own header and body, the card.
Preview
Section titled “Preview”<div style="display: grid; gap: 1.5rem; width: 100%; max-width: 28rem">
<nana-item-group label="Policies" divided>
<nana-item
title="Motor comprehensive"
description="KDA 123A · renews 12 March"
href="#policies"
>
<nana-icon slot="media" name="truck"></nana-icon>
<nana-button slot="actions" size="sm" variant="ghost">Renew</nana-button>
</nana-item>
<nana-item
title="Health family cover"
description="Four people · paid monthly"
href="#policies"
>
<nana-icon slot="media" name="heart"></nana-icon>
<nana-button slot="actions" size="sm" variant="ghost">Renew</nana-button>
</nana-item>
<nana-item
title="Home contents"
description="Kilimani flat · lapsed"
href="#policies"
>
<nana-icon slot="media" name="shield-check"></nana-icon>
<nana-button slot="actions" size="sm" variant="ghost">Renew</nana-button>
</nana-item>
</nana-item-group>
<nana-item
variant="outline"
media="avatar"
title="Wanjiru Kamau"
description="Claims assessor, Nairobi"
>
<nana-avatar slot="media" name="Wanjiru Kamau"></nana-avatar>
<nana-button slot="actions" size="sm" variant="tertiary">
Assign
</nana-button>
</nana-item>
</div> KDA 123A · renews 12 March
Four people · paid monthly
Kilimani flat · lapsed
Claims assessor, Nairobi
<script lang="ts">
import { heartIcon, shieldCheckIcon, truckIcon } from '@nana-tec/ui-core/heroicons';
import { NanaAvatar, NanaButton, NanaIcon, NanaItem, NanaItemGroup } from '$lib';
const policies = [
{ icon: truckIcon, title: 'Motor comprehensive', description: 'KDA 123A · renews 12 March' },
{ icon: heartIcon, title: 'Health family cover', description: 'Four people · paid monthly' },
{ icon: shieldCheckIcon, title: 'Home contents', description: 'Kilimani flat · lapsed' },
];
</script>
<div class="grid w-full max-w-md gap-6">
<NanaItemGroup label="Policies" divided>
{#each policies as policy (policy.title)}
<NanaItem title={policy.title} description={policy.description} href="#policies">
{#snippet media()}<NanaIcon icon={policy.icon} />{/snippet}
{#snippet actions()}<NanaButton size="sm" variant="ghost">Renew</NanaButton>{/snippet}
</NanaItem>
{/each}
</NanaItemGroup>
<NanaItem
variant="outline"
mediaVariant="avatar"
title="Wanjiru Kamau"
description="Claims assessor, Nairobi"
>
{#snippet media()}<NanaAvatar name="Wanjiru Kamau" />{/snippet}
{#snippet actions()}<NanaButton size="sm" variant="tertiary">Assign</NanaButton>{/snippet}
</NanaItem>
</div> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add item --framework web-componentsnpx @nana-tec/ui add item --framework svelteLands in src/lib/components/ui/item/ as NanaItem.svelte and NanaItemGroup.svelte, with
their classes in styles/item.ts. Classes resolve to the design tokens. Requires Tailwind v4.
<script lang="ts"> import { NanaItem, NanaItemGroup } from '$lib/components/ui/item';</script>
<NanaItemGroup label="Policies" divided> <NanaItem title="Motor comprehensive" description="KDA 123A" href="/policies/42"> {#snippet media()}<NanaIcon icon={truckIcon} />{/snippet} {#snippet actions()}<NanaButton size="sm" variant="ghost">Renew</NanaButton>{/snippet} </NanaItem></NanaItemGroup>Anything passed as children shows under the description.
Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and
each component downloads only the first time a page uses it:
import "@nana-tec/ui-components/autoloader";import "@nana-tec/ui-components/theme";The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.
Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:
import "@nana-tec/ui-components/item";
Copied in with npx @nana-tec/ui add item? Import your project's own
@/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.
<nana-item-group label="Policies" divided> <nana-item title="Motor comprehensive" description="KDA 123A" href="/policies/42"> <nana-icon slot="media" name="truck"></nana-icon> <nana-button slot="actions" size="sm" variant="ghost">Renew</nana-button> </nana-item></nana-item-group>Content in the default slot shows under the description.
Opening the row
Section titled “Opening the row”With href, the title becomes a link stretched over the whole row, so a click anywhere on it
opens the item, and the row tints on hover and presses in slightly. The actions sit above
the link and do their own thing. Keyboard users reach the link and then each action, in
order. A disabled item dims, and its link stays announced but goes nowhere.
Looks and sizes
Section titled “Looks and sizes”| Variant | Use |
|---|---|
default | No border or fill; for rows in a divided group or a panel |
outline | A light border on the surface, for an item on its own |
muted | A tinted fill, for an item that sits back |
size is md or the denser sm. The media box is sized for an icon by default; set the
media to avatar to let an avatar keep its own size, or image to fill the box with a
picture.
Groups
Section titled “Groups”A group is a list, named by label, and its items are its list items. Items are spaced
apart; with divided they are joined in one outlined box with a line between each.
Accessibility
Section titled “Accessibility”- A group is a
listnamed bylabel, and each item in it alistitem, so screen readers say how many there are. - The title is the link’s name, so it should say what opens: “Motor comprehensive”, not “View”.
- Actions are separate buttons, never inside the link; name an icon-only action, as in “Renew motor comprehensive”.
- Media is decoration unless it says something the title does not; an avatar with a name already has one.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
description | description | string | '' | A line under the title, clamped to two lines |
disabled | disabled | boolean | false | Dims the row and stops the link |
href | href | string | '' | Where the row leads; the title becomes a link stretched over the row |
media | media | ItemMedia | 'icon' | What the media slot holds, which sets its box |
rel | rel | string | '' | The link's relationship |
size | size | ItemSize | 'md' | The row's density |
target | target | '_blank' | '_self' | '_parent' | '_top' | '' | '' | Where the link opens |
title | title | string | '' | The row's title |
variant | variant | ItemVariant | 'default' | The look of the row |
Slots
| Slot | Description |
|---|---|
media | An icon, avatar or image at the start |
(default) | Extra content under the description |
actions | Buttons at the end, clickable on their own |
CSS parts
| Part | Description |
|---|---|
::part(base) | The row, with interactive when it has a link and disabled when disabled |
::part(media) | The media box |
::part(content) | The title, description and extra content |
::part(title) | The title |
::part(link) | The title's link, stretched over the row |
::part(description) | The description |
::part(actions) | The actions box |
CSS custom properties
| Property | Description |
|---|---|
--nana-item-bg | Background of the row |
--nana-item-border | Border of the row |
--nana-item-divider | Colour of the line above the row in a divided group |
--nana-item-radius | Corner radius of the row |
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
divided | divided | boolean | false | Joins the items in one outlined box with lines between them |
label | label | string | '' | Names the list for screen readers |
Slots
| Slot | Description |
|---|---|
(default) | nana-item children |
CSS parts
| Part | Description |
|---|---|
::part(list) | The list around the items, with divided when joined |
NanaItem
| Prop | Type | Default |
|---|---|---|
variant | ItemVariant | 'default' |
size | ItemSize | 'md' |
title | string | |
description | string | |
href | string | |
disabled | boolean | false |
mediaVariant | ItemMedia | 'icon' |
media | Snippet | |
actions | Snippet | |
children | Snippet |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'title'>.
NanaItemGroup
| Prop | Type | Default |
|---|---|---|
label | string | |
divided | boolean | false |
children | Snippet |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.