- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";
const itemVariants = cva(
"group/item flex w-full flex-wrap items-center gap-3 rounded-lg border px-4 py-3 text-sm transition-colors",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "border-border bg-card text-card-foreground",
muted: "bg-muted text-foreground border-transparent",
outline: "border-border bg-transparent",
},
},
}
);
type ItemProps = React.ComponentPropsWithoutRef<"div"> &
VariantProps<typeof itemVariants> & {
as?: React.ElementType;
asChild?: boolean;
};
function Item({
as,
asChild,
children,
className,
variant,
...props
}: ItemProps) {
const mergedClass = cn(itemVariants({ variant }), className);
if (asChild && React.isValidElement(children)) {
const child = children as React.ReactElement<{ className?: string }>;
return React.cloneElement(child, {
...props,
className: cn(mergedClass, child.props.className),
"data-slot": "item",
"data-variant": variant,
} as never);
}
const Comp = (as ?? "div") as React.ElementType;
return (
<Comp
className={mergedClass}
data-slot="item"
data-variant={variant}
{...props}
>
{children}
</Comp>
);
}
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex flex-col gap-2", className)}
data-slot="item-group"
{...props}
/>
);
}
function ItemMedia({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
className
)}
data-slot="item-media"
{...props}
/>
);
}
function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex min-w-0 flex-1 flex-col gap-0.5", className)}
data-slot="item-content"
{...props}
/>
);
}
function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("truncate text-sm leading-tight font-medium", className)}
data-slot="item-title"
{...props}
/>
);
}
function ItemDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("text-muted-foreground text-sm", className)}
data-slot="item-description"
{...props}
/>
);
}
function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex shrink-0 items-center gap-2", className)}
data-slot="item-actions"
{...props}
/>
);
}
export {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
};Item is a flexible row primitive for grouping media, content, and actions. Use it for settings lists, activity feeds, user rows, or any horizontal layout with a leading visual and trailing controls.
Installation
$ bunx --bun frakment add item$ npx frakment add item$ pnpm dlx frakment add item$ yarn dlx frakment add item
Install the following dependencies:
$ bun add class-variance-authority$ npm install class-variance-authority$ pnpm add class-variance-authority$ yarn add class-variance-authority
Optional — install avatar to replicate the full demo:
$ bunx --bun frakment add avatar$ npx frakment add avatar$ pnpm dlx frakment add avatar$ yarn dlx frakment add avatar
The demo uses <Avatar> with the 5 AVIF avatars included in the avatar component. Skip this step if you only need the Item primitive.
Copy and paste the following code into your project.
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";
const itemVariants = cva(
"group/item flex w-full flex-wrap items-center gap-3 rounded-lg border px-4 py-3 text-sm transition-colors",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "border-border bg-card text-card-foreground",
muted: "bg-muted text-foreground border-transparent",
outline: "border-border bg-transparent",
},
},
}
);
type ItemProps = React.ComponentPropsWithoutRef<"div"> &
VariantProps<typeof itemVariants> & {
as?: React.ElementType;
asChild?: boolean;
};
function Item({
as,
asChild,
children,
className,
variant,
...props
}: ItemProps) {
const mergedClass = cn(itemVariants({ variant }), className);
if (asChild && React.isValidElement(children)) {
const child = children as React.ReactElement<{ className?: string }>;
return React.cloneElement(child, {
...props,
className: cn(mergedClass, child.props.className),
"data-slot": "item",
"data-variant": variant,
} as never);
}
const Comp = (as ?? "div") as React.ElementType;
return (
<Comp
className={mergedClass}
data-slot="item"
data-variant={variant}
{...props}
>
{children}
</Comp>
);
}
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex flex-col gap-2", className)}
data-slot="item-group"
{...props}
/>
);
}
function ItemMedia({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
className
)}
data-slot="item-media"
{...props}
/>
);
}
function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex min-w-0 flex-1 flex-col gap-0.5", className)}
data-slot="item-content"
{...props}
/>
);
}
function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("truncate text-sm leading-tight font-medium", className)}
data-slot="item-title"
{...props}
/>
);
}
function ItemDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("text-muted-foreground text-sm", className)}
data-slot="item-description"
{...props}
/>
);
}
function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex shrink-0 items-center gap-2", className)}
data-slot="item-actions"
{...props}
/>
);
}
export {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
};Update the import paths to match your project setup.
Usage
import { Item, ItemContent, ItemMedia, ItemTitle } from "@/components/ui/item";
<DocsBaseSwitcher base="web" component="item" className="mb-6" /><Item>
<ItemMedia>JS</ItemMedia>
<ItemContent>
<ItemTitle>Jane Smith</ItemTitle>
</ItemContent>
</Item>Composition
Item
├── ItemMedia
├── ItemContent
│ ├── ItemTitle
│ └── ItemDescription
└── ItemActionsVariants
Three styles: default (bordered card), outline (transparent with border), muted (soft background, no border).
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";
const itemVariants = cva(
"group/item flex w-full flex-wrap items-center gap-3 rounded-lg border px-4 py-3 text-sm transition-colors",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "border-border bg-card text-card-foreground",
muted: "bg-muted text-foreground border-transparent",
outline: "border-border bg-transparent",
},
},
}
);
type ItemProps = React.ComponentPropsWithoutRef<"div"> &
VariantProps<typeof itemVariants> & {
as?: React.ElementType;
asChild?: boolean;
};
function Item({
as,
asChild,
children,
className,
variant,
...props
}: ItemProps) {
const mergedClass = cn(itemVariants({ variant }), className);
if (asChild && React.isValidElement(children)) {
const child = children as React.ReactElement<{ className?: string }>;
return React.cloneElement(child, {
...props,
className: cn(mergedClass, child.props.className),
"data-slot": "item",
"data-variant": variant,
} as never);
}
const Comp = (as ?? "div") as React.ElementType;
return (
<Comp
className={mergedClass}
data-slot="item"
data-variant={variant}
{...props}
>
{children}
</Comp>
);
}
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex flex-col gap-2", className)}
data-slot="item-group"
{...props}
/>
);
}
function ItemMedia({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
className
)}
data-slot="item-media"
{...props}
/>
);
}
function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex min-w-0 flex-1 flex-col gap-0.5", className)}
data-slot="item-content"
{...props}
/>
);
}
function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("truncate text-sm leading-tight font-medium", className)}
data-slot="item-title"
{...props}
/>
);
}
function ItemDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("text-muted-foreground text-sm", className)}
data-slot="item-description"
{...props}
/>
);
}
function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex shrink-0 items-center gap-2", className)}
data-slot="item-actions"
{...props}
/>
);
}
export {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
};With media
Put an icon, avatar, or badge in ItemMedia. Icons without a size-* class are auto-sized to 16px.
A
B
C
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";
const itemVariants = cva(
"group/item flex w-full flex-wrap items-center gap-3 rounded-lg border px-4 py-3 text-sm transition-colors",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "border-border bg-card text-card-foreground",
muted: "bg-muted text-foreground border-transparent",
outline: "border-border bg-transparent",
},
},
}
);
type ItemProps = React.ComponentPropsWithoutRef<"div"> &
VariantProps<typeof itemVariants> & {
as?: React.ElementType;
asChild?: boolean;
};
function Item({
as,
asChild,
children,
className,
variant,
...props
}: ItemProps) {
const mergedClass = cn(itemVariants({ variant }), className);
if (asChild && React.isValidElement(children)) {
const child = children as React.ReactElement<{ className?: string }>;
return React.cloneElement(child, {
...props,
className: cn(mergedClass, child.props.className),
"data-slot": "item",
"data-variant": variant,
} as never);
}
const Comp = (as ?? "div") as React.ElementType;
return (
<Comp
className={mergedClass}
data-slot="item"
data-variant={variant}
{...props}
>
{children}
</Comp>
);
}
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex flex-col gap-2", className)}
data-slot="item-group"
{...props}
/>
);
}
function ItemMedia({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
className
)}
data-slot="item-media"
{...props}
/>
);
}
function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex min-w-0 flex-1 flex-col gap-0.5", className)}
data-slot="item-content"
{...props}
/>
);
}
function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("truncate text-sm leading-tight font-medium", className)}
data-slot="item-title"
{...props}
/>
);
}
function ItemDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("text-muted-foreground text-sm", className)}
data-slot="item-description"
{...props}
/>
);
}
function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex shrink-0 items-center gap-2", className)}
data-slot="item-actions"
{...props}
/>
);
}
export {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
};With description
Add ItemDescription below ItemTitle for a secondary line.
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";
const itemVariants = cva(
"group/item flex w-full flex-wrap items-center gap-3 rounded-lg border px-4 py-3 text-sm transition-colors",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "border-border bg-card text-card-foreground",
muted: "bg-muted text-foreground border-transparent",
outline: "border-border bg-transparent",
},
},
}
);
type ItemProps = React.ComponentPropsWithoutRef<"div"> &
VariantProps<typeof itemVariants> & {
as?: React.ElementType;
asChild?: boolean;
};
function Item({
as,
asChild,
children,
className,
variant,
...props
}: ItemProps) {
const mergedClass = cn(itemVariants({ variant }), className);
if (asChild && React.isValidElement(children)) {
const child = children as React.ReactElement<{ className?: string }>;
return React.cloneElement(child, {
...props,
className: cn(mergedClass, child.props.className),
"data-slot": "item",
"data-variant": variant,
} as never);
}
const Comp = (as ?? "div") as React.ElementType;
return (
<Comp
className={mergedClass}
data-slot="item"
data-variant={variant}
{...props}
>
{children}
</Comp>
);
}
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex flex-col gap-2", className)}
data-slot="item-group"
{...props}
/>
);
}
function ItemMedia({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
className
)}
data-slot="item-media"
{...props}
/>
);
}
function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex min-w-0 flex-1 flex-col gap-0.5", className)}
data-slot="item-content"
{...props}
/>
);
}
function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("truncate text-sm leading-tight font-medium", className)}
data-slot="item-title"
{...props}
/>
);
}
function ItemDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("text-muted-foreground text-sm", className)}
data-slot="item-description"
{...props}
/>
);
}
function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex shrink-0 items-center gap-2", className)}
data-slot="item-actions"
{...props}
/>
);
}
export {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
};With actions
Add ItemActions as the last child for a trailing button, badge, or amount.
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";
const itemVariants = cva(
"group/item flex w-full flex-wrap items-center gap-3 rounded-lg border px-4 py-3 text-sm transition-colors",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "border-border bg-card text-card-foreground",
muted: "bg-muted text-foreground border-transparent",
outline: "border-border bg-transparent",
},
},
}
);
type ItemProps = React.ComponentPropsWithoutRef<"div"> &
VariantProps<typeof itemVariants> & {
as?: React.ElementType;
asChild?: boolean;
};
function Item({
as,
asChild,
children,
className,
variant,
...props
}: ItemProps) {
const mergedClass = cn(itemVariants({ variant }), className);
if (asChild && React.isValidElement(children)) {
const child = children as React.ReactElement<{ className?: string }>;
return React.cloneElement(child, {
...props,
className: cn(mergedClass, child.props.className),
"data-slot": "item",
"data-variant": variant,
} as never);
}
const Comp = (as ?? "div") as React.ElementType;
return (
<Comp
className={mergedClass}
data-slot="item"
data-variant={variant}
{...props}
>
{children}
</Comp>
);
}
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex flex-col gap-2", className)}
data-slot="item-group"
{...props}
/>
);
}
function ItemMedia({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
className
)}
data-slot="item-media"
{...props}
/>
);
}
function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex min-w-0 flex-1 flex-col gap-0.5", className)}
data-slot="item-content"
{...props}
/>
);
}
function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("truncate text-sm leading-tight font-medium", className)}
data-slot="item-title"
{...props}
/>
);
}
function ItemDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("text-muted-foreground text-sm", className)}
data-slot="item-description"
{...props}
/>
);
}
function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex shrink-0 items-center gap-2", className)}
data-slot="item-actions"
{...props}
/>
);
}
export {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
};In context
Combine with Spinner for a live processing row.
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";
const itemVariants = cva(
"group/item flex w-full flex-wrap items-center gap-3 rounded-lg border px-4 py-3 text-sm transition-colors",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "border-border bg-card text-card-foreground",
muted: "bg-muted text-foreground border-transparent",
outline: "border-border bg-transparent",
},
},
}
);
type ItemProps = React.ComponentPropsWithoutRef<"div"> &
VariantProps<typeof itemVariants> & {
as?: React.ElementType;
asChild?: boolean;
};
function Item({
as,
asChild,
children,
className,
variant,
...props
}: ItemProps) {
const mergedClass = cn(itemVariants({ variant }), className);
if (asChild && React.isValidElement(children)) {
const child = children as React.ReactElement<{ className?: string }>;
return React.cloneElement(child, {
...props,
className: cn(mergedClass, child.props.className),
"data-slot": "item",
"data-variant": variant,
} as never);
}
const Comp = (as ?? "div") as React.ElementType;
return (
<Comp
className={mergedClass}
data-slot="item"
data-variant={variant}
{...props}
>
{children}
</Comp>
);
}
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex flex-col gap-2", className)}
data-slot="item-group"
{...props}
/>
);
}
function ItemMedia({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
className
)}
data-slot="item-media"
{...props}
/>
);
}
function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex min-w-0 flex-1 flex-col gap-0.5", className)}
data-slot="item-content"
{...props}
/>
);
}
function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("truncate text-sm leading-tight font-medium", className)}
data-slot="item-title"
{...props}
/>
);
}
function ItemDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("text-muted-foreground text-sm", className)}
data-slot="item-description"
{...props}
/>
);
}
function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex shrink-0 items-center gap-2", className)}
data-slot="item-actions"
{...props}
/>
);
}
export {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
};In Context
Settings row
"use client";
import { Button } from "@/components/ui/button";
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemMedia,
ItemTitle,
} from "@/components/ui/item";
export function ItemSettings() {
return (
<div className="mx-auto w-full max-w-sm">
<Item variant="outline">
<ItemMedia>
<span className="bg-muted flex size-8 items-center justify-center rounded-full text-xs font-medium">
AR
</span>
</ItemMedia>
<ItemContent>
<ItemTitle>Jane Doe</ItemTitle>
<ItemDescription>john@example.com</ItemDescription>
</ItemContent>
<ItemActions>
<Button size="sm" variant="outline">
Edit
</Button>
</ItemActions>
</Item>
</div>
);
}API Reference
Item
| Prop | Type | Default | Description |
|---|---|---|---|
variant | defaultoutlinemuted | default | Visual style of the row. |
ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions
Extend React.ComponentProps<"div">. Each maps to a data-slot attribute for CSS targeting.
As prop
Item also accepts an as prop to render a custom element such as <a> or <li>.
Data Attributes
| Attribute | Values |
|---|---|
data-slot | item, item-group, item-media, item-content, item-title, item-description, item-actions |
data-variant | default | outline | muted |
data-size | default | sm |
Accessibility
Itemrenders a<div>— for interactive rows, useaswith<a>or<button>so keyboard and screen readers work.ItemMediashould bearia-hiddenwhen the visual is decorative (e.g., a status dot).ItemTitleacts as the accessible name — write it as a short label.
Best Practices
- Use for list rows with mixed content. Media + content + actions fits in one Item.
- Keep the media square. A 32px to 40px square reads as an avatar or icon.
- Actions belong in
ItemActions. Do not float buttons inside content. - One action cluster. More than three actions belong in a dropdown.
Related Components
- Card — elevated container
- Marker — inline status row
- Attachment — file row