Item
SaveA list row with media, a title, a description, and trailing actions, for settings and lists, with a group that separates rows with hairlines.
- Category
- Layout
- Version
- 0.1.1
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Item preview
Installation
npx @shakenui/cli add itemReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add item --dry-runUsage
item-example.tsx
import { Badge } from "@/components/shaken/ui/badge";
import { Button } from "@/components/shaken/ui/button";
import { Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle } from "@/components/shaken/ui/item";
const icon = { "aria-hidden": true, viewBox: "0 0 16 16", fill: "none" } as const;
const stroke = { stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round" } as const;
export default function ItemExample() {
return (
<div className="flex w-full max-w-lg flex-col gap-6">
<section className="flex flex-col gap-2">
<h3 id="integrations-heading" className="m-0 text-xs font-medium text-zinc-500">
Integrations
</h3>
<ItemGroup aria-labelledby="integrations-heading">
<Item>
<ItemMedia variant="icon">
<svg {...icon}>
<circle cx="4.5" cy="3.75" r="1.5" {...stroke} />
<circle cx="4.5" cy="12.25" r="1.5" {...stroke} />
<circle cx="11.5" cy="5.75" r="1.5" {...stroke} />
<path d="M4.5 5.25v5.5M11.5 7.25c0 2.5-3 2.25-6.25 3.75" {...stroke} />
</svg>
</ItemMedia>
<ItemContent>
<ItemTitle>
Git repositories
<Badge tone="success">Connected</Badge>
</ItemTitle>
<ItemDescription>Agents can open branches and pull requests in 4 repositories.</ItemDescription>
</ItemContent>
<ItemActions>
<Button variant="ghost" size="sm">
Configure
</Button>
</ItemActions>
</Item>
<Item>
<ItemMedia variant="icon">
<svg {...icon}>
<path d="M2.75 4.25c0-.83.67-1.5 1.5-1.5h7.5c.83 0 1.5.67 1.5 1.5v5c0 .83-.67 1.5-1.5 1.5H7l-3 2.5v-2.5h0a1.25 1.25 0 0 1-1.25-1.25z" {...stroke} />
</svg>
</ItemMedia>
<ItemContent>
<ItemTitle>
Team chat
<Badge tone="warning">Token expired</Badge>
</ItemTitle>
<ItemDescription>Approval requests are not being delivered. Reconnect to resume them.</ItemDescription>
</ItemContent>
<ItemActions>
<Button size="sm">Reconnect</Button>
</ItemActions>
</Item>
<Item>
<ItemMedia variant="icon">
<svg {...icon}>
<circle cx="8" cy="8" r="5.25" {...stroke} />
<path d="M8 5.5V8l1.75 1.25" {...stroke} />
</svg>
</ItemMedia>
<ItemContent>
<ItemTitle>
Issue tracker
<Badge tone="info" dot pulse>
Syncing
</Badge>
</ItemTitle>
<ItemDescription>Importing 1,284 issues so agents can link their work to tickets.</ItemDescription>
</ItemContent>
<ItemActions>
<span className="font-mono text-xs text-zinc-500 tabular-nums">62%</span>
</ItemActions>
</Item>
</ItemGroup>
</section>
<Item variant="outline" size="sm" render={<a href="#usage" />}>
<ItemMedia>
<svg {...icon}>
<path d="M2.75 13.25h10.5M4.5 10.5V8M8 10.5V4.5M11.5 10.5V6.5" {...stroke} />
</svg>
</ItemMedia>
<ItemContent>
<ItemTitle>Usage this month</ItemTitle>
<ItemDescription>2.4M tokens across 318 agent runs</ItemDescription>
</ItemContent>
<ItemActions>
<svg {...icon} className="size-4 text-zinc-400 transition-[translate] duration-150 ease-out group-hover/item:translate-x-0.5 motion-reduce:transition-none dark:text-zinc-500">
<path d="M6.25 4.25 10 8l-3.75 3.75" {...stroke} />
</svg>
</ItemActions>
</Item>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "plain" | "outline" | "plain" | plain has no frame (rows in an ItemGroup); outline draws its own hairline container. |
| size | "sm" | "md" | "md" | Padding and gap. |
| render | ReactElement | — | Makes the whole row a link or button, for example render={<a href="/usage" />}; adds a hover tint and focus ring. |
| ItemMedia variant | "plain" | "icon" | "avatar" | "image" | "plain" | An icon as is, an icon in a 32px hairline tile, a 40px round avatar, or a 48px thumbnail. |
| ItemTitle / ItemDescription | ComponentProps<"div"> / ComponentProps<"p"> | — | Name and supporting text. The description clamps to two lines. |
| ItemActions | ComponentProps<"div"> | — | Trailing buttons, switches, menus, or meta text. Never shrinks. |
| ItemGroup framed | boolean | true | Draws the hairline container around the rows. Turn off inside a card. |
Accessibility
- ItemGroup renders role="list" and each Item inside it role="listitem"; name the group with aria-label or aria-labelledby.
- An Item rendered as a link keeps its link role and is wrapped in a listitem element, so the list stays valid.
- Interactive rows show an inset sky focus ring on keyboard focus; hover only tints the background.
- ItemMedia is decorative; put the meaning in the title or a Badge (the example states each connection's status in text).
- Hover tint transitions are removed with reduced motion.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/item.tsxitem- Also installs button@0.2.1registry dependency
- Also installs badge@0.2.1registry dependency
- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/item/0.1.1.json.
ui/item.tsxShowHide
ui/item.tsx
"use client";
import { mergeProps } from "@base-ui/react/merge-props";
import { useRender } from "@base-ui/react/use-render";
import { type ComponentProps, createContext, useContext } from "react";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
const InGroupContext = createContext(false);
const variants = {
/** No frame; for rows inside a group, a card, or a panel. */
plain: "",
/** Its own hairline container, for a standalone row. */
outline: cx(
"rounded-xl border border-zinc-950/10 bg-white shadow-[0_1px_2px_rgb(0_0_0/0.04)]",
"dark:border-white/10 dark:bg-black dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]",
),
} as const;
const sizes = {
sm: "gap-3 px-3 py-2.5",
md: "gap-3.5 px-4 py-3.5",
} as const;
export type ItemVariant = keyof typeof variants;
export type ItemSize = keyof typeof sizes;
export interface ItemProps extends useRender.ComponentProps<"div"> {
/** `plain` has no frame (rows in an `ItemGroup`); `outline` draws its own hairline container. */
variant?: ItemVariant;
/** Padding and gap. `sm` suits dense lists and menus, `md` suits settings rows. */
size?: ItemSize;
}
/**
* A row with optional media, a title and description, and trailing actions. Renders a `<div>`;
* pass `render={<a href="…" />}` (or your router's link) to make the whole row a link, which adds
* a hover tint and focus ring. Inside an `ItemGroup` it becomes a list item.
*/
export function Item({ variant = "plain", size = "md", render, className, ...props }: ItemProps) {
const inGroup = useContext(InGroupContext);
const element = useRender({
defaultTagName: "div",
render,
props: mergeProps<"div">(
{
role: inGroup && !render ? "listitem" : undefined,
className: cx(
"group/item relative flex min-w-0 items-center text-left text-sm no-underline outline-none",
"text-zinc-950 dark:text-white",
variants[variant],
sizes[size],
// Interactive rows (links, buttons) get a hover tint and an inset focus ring.
"[&:is(a,button)]:transition-colors [&:is(a,button)]:duration-150 [&:is(a,button)]:ease-out motion-reduce:transition-none",
"[&:is(a,button)]:hover:bg-zinc-950/[0.03] dark:[&:is(a,button)]:hover:bg-white/[0.04]",
"focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-sky-500",
className,
),
},
props,
),
});
// A link or button keeps its own role, so in a list it gets a listitem wrapper instead.
return inGroup && render ? <div role="listitem">{element}</div> : element;
}
const mediaVariants = {
/** The icon as is, in the tertiary text color. */
plain: "text-zinc-500 [&_svg]:size-5",
/** A 32px hairline tile around the icon. */
icon: cx(
"size-8 rounded-lg border border-zinc-950/10 text-zinc-700 shadow-[0_1px_2px_rgb(0_0_0/0.04)] [&_svg]:size-4",
"dark:border-white/15 dark:text-zinc-300 dark:shadow-none",
),
/** A 40px round frame for an avatar image or initials. */
avatar: cx(
"size-10 overflow-hidden rounded-full border border-zinc-950/10 text-xs font-medium text-zinc-600 dark:border-white/15 dark:text-zinc-300",
"[&>img]:size-full [&>img]:object-cover",
),
/** A 48px rounded frame for a thumbnail. */
image: "size-12 overflow-hidden rounded-lg border border-zinc-950/10 dark:border-white/10 [&>img]:size-full [&>img]:object-cover",
} as const;
export type ItemMediaVariant = keyof typeof mediaVariants;
export interface ItemMediaProps extends ComponentProps<"div"> {
variant?: ItemMediaVariant;
}
/** Leading media: an icon, avatar, thumbnail, or status glyph. Decorative by default; label it if it carries meaning. */
export function ItemMedia({ variant = "plain", className, ...props }: ItemMediaProps) {
return (
<div
className={cx("flex shrink-0 items-center justify-center self-start [&_svg]:shrink-0", mediaVariants[variant], className)}
{...props}
/>
);
}
/** Holds the title and description; takes the remaining width and lets long text truncate or wrap. */
export function ItemContent({ className, ...props }: ComponentProps<"div">) {
return <div className={cx("flex min-w-0 flex-1 flex-col gap-0.5", className)} {...props} />;
}
/** The row's name. A badge or count sits inline after the text and wraps below it when space runs out. */
export function ItemTitle({ className, ...props }: ComponentProps<"div">) {
return <div className={cx("flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 leading-5 font-medium text-zinc-950 dark:text-white", className)} {...props} />;
}
/** One or two lines of supporting text in the secondary color. Clamped to two lines. */
export function ItemDescription({ className, ...props }: ComponentProps<"p">) {
return <p className={cx("m-0 line-clamp-2 leading-5 text-zinc-600 dark:text-zinc-400", className)} {...props} />;
}
/** Trailing controls: buttons, a switch, a menu, or meta text. Never shrinks. */
export function ItemActions({ className, ...props }: ComponentProps<"div">) {
return <div className={cx("flex shrink-0 items-center gap-2", className)} {...props} />;
}
export interface ItemGroupProps extends ComponentProps<"div"> {
/** Draws the hairline container around the rows. Turn off when the group already sits in a card. */
framed?: boolean;
}
/**
* A list of items separated by hairline dividers. Announced as a list with its item count;
* give it an `aria-label` or `aria-labelledby` naming what it lists.
*/
export function ItemGroup({ framed = true, className, ...props }: ItemGroupProps) {
return (
<InGroupContext.Provider value={true}>
<div
role="list"
className={cx(
"flex flex-col divide-y divide-zinc-950/[0.07] dark:divide-white/[0.08]",
framed &&
"overflow-hidden",
framed &&
cx(
"rounded-xl border border-zinc-950/10 bg-white shadow-[0_1px_2px_rgb(0_0_0/0.04)]",
"dark:border-white/10 dark:bg-black dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]",
),
className,
)}
{...props}
/>
</InGroupContext.Provider>
);
}