Skip to content
Shaken UI
Sign in

Item

Save

A 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

Integrations

Git repositoriesConnected

Agents can open branches and pull requests in 4 repositories.

Team chatToken expired

Approval requests are not being delivered. Reconnect to resume them.

Issue trackerSyncing

Importing 1,284 issues so agents can link their work to tickets.

62%
Usage this month

2.4M tokens across 318 agent runs

Installation

npx @shakenui/cli add item

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add item --dry-run

Usage

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

PropTypeDefaultDescription
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.
renderReactElement—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 / ItemDescriptionComponentProps<"div"> / ComponentProps<"p">—Name and supporting text. The description clamps to two lines.
ItemActionsComponentProps<"div">—Trailing buttons, switches, menus, or meta text. Never shrinks.
ItemGroup framedbooleantrueDraws 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.tsxShow
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>
  );
}