Item
Composable list item with media, content, title, description, and action slots.
Report Q4.pdf
Modified 2 hours ago
Hero image.png
Modified yesterday
Intro reel.mp4
Modified last week
import { FileTextIcon, ImageIcon, VideoIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import {
Item,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemSeparator,
ItemTitle,
} from "@/components/ui/item";
const files = [
{
icon: FileTextIcon,
name: "Report Q4.pdf",
desc: "Modified 2 hours ago",
badge: "PDF",
},
{
icon: ImageIcon,
name: "Hero image.png",
desc: "Modified yesterday",
badge: "PNG",
},
{
icon: VideoIcon,
name: "Intro reel.mp4",
desc: "Modified last week",
badge: "MP4",
},
];
const ItemDemo = () => {
return (
<ItemGroup className="max-w-sm">
{files.map((file, i) => (
<>
{i > 0 && <ItemSeparator key={`sep-${file.name}`} />}
<Item key={file.name} variant="outline">
<ItemMedia variant="icon">
<file.icon />
</ItemMedia>
<ItemContent>
<ItemTitle>{file.name}</ItemTitle>
<ItemDescription>{file.desc}</ItemDescription>
</ItemContent>
<Badge variant="outline" className="ml-auto">
{file.badge}
</Badge>
</Item>
</>
))}
</ItemGroup>
);
};
export default ItemDemo;
Installation
npx shadcn@latest add @ark-cn/itemInstall the dependency required by this primitive:
npm install @ark-ui/react class-variance-authorityCopy the component source into your app:
TSXcomponents/ui/item.tsx
"use client";
import { ark } from "@ark-ui/react/factory";
import { cva, type VariantProps } from "class-variance-authority";
import type { ComponentProps } from "react";
import { Separator } from "@/components/ui/separator";
import { cn } from "@/lib/utils";
export const ItemGroup = ({
className,
...props
}: ComponentProps<typeof ark.div>) => {
return (
<ark.div
role="list"
data-slot="item-group"
className={cn(
"group/item-group flex w-full flex-col gap-4 has-data-[size=sm]:gap-2.5 has-data-[size=xs]:gap-2",
className,
)}
{...props}
/>
);
};
export const ItemSeparator = ({
className,
...props
}: ComponentProps<typeof Separator>) => {
return (
<Separator
data-slot="item-separator"
orientation="horizontal"
className={cn("my-2", className)}
{...props}
/>
);
};
export const itemVariants = cva(
"group/item flex w-full flex-wrap items-center rounded-lg border text-sm transition-colors duration-100 outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 [a&]:transition-colors [a&]:hover:bg-muted",
{
variants: {
variant: {
default: "border-transparent",
outline: "border-border",
muted: "border-transparent bg-muted/50",
},
size: {
default: "gap-2.5 px-3 py-2.5",
sm: "gap-2.5 px-3 py-2.5",
xs: "gap-2 px-2.5 py-2 in-data-[slot=menu-content]:p-0",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
},
);
export interface ItemProps
extends ComponentProps<typeof ark.div>,
VariantProps<typeof itemVariants> {}
export const Item = ({
className,
variant = "default",
size = "default",
...props
}: ItemProps) => {
return (
<ark.div
data-slot="item"
data-variant={variant}
data-size={size}
className={cn(itemVariants({ variant, size, className }))}
{...props}
/>
);
};
export const itemMediaVariants = cva(
"flex shrink-0 items-center justify-center gap-2 group-has-data-[slot=item-description]/item:translate-y-0.5 group-has-data-[slot=item-description]/item:self-start [&_svg]:pointer-events-none",
{
variants: {
variant: {
default: "bg-transparent",
icon: "[&_svg:not([class*='size-'])]:size-4",
image:
"size-10 overflow-hidden rounded-sm group-data-[size=sm]/item:size-8 group-data-[size=xs]/item:size-6 [&_img]:size-full [&_img]:object-cover",
},
},
defaultVariants: {
variant: "default",
},
},
);
export interface ItemMediaProps
extends ComponentProps<typeof ark.div>,
VariantProps<typeof itemMediaVariants> {}
export const ItemMedia = ({
className,
variant = "default",
...props
}: ItemMediaProps) => {
return (
<ark.div
data-slot="item-media"
data-variant={variant}
className={cn(itemMediaVariants({ variant, className }))}
{...props}
/>
);
};
export const ItemContent = ({
className,
...props
}: ComponentProps<typeof ark.div>) => {
return (
<ark.div
data-slot="item-content"
className={cn(
"flex flex-1 flex-col gap-1 group-data-[size=xs]/item:gap-0 [&+[data-slot=item-content]]:flex-none",
className,
)}
{...props}
/>
);
};
export const ItemTitle = ({
className,
...props
}: ComponentProps<typeof ark.div>) => {
return (
<ark.div
data-slot="item-title"
className={cn(
"line-clamp-1 flex w-fit items-center gap-2 text-sm leading-snug font-medium underline-offset-4",
className,
)}
{...props}
/>
);
};
export const ItemDescription = ({
className,
...props
}: ComponentProps<typeof ark.p>) => {
return (
<ark.p
data-slot="item-description"
className={cn(
"line-clamp-2 text-left text-sm leading-normal font-normal text-muted-foreground group-data-[size=xs]/item:text-xs [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
className,
)}
{...props}
/>
);
};
export const ItemActions = ({
className,
...props
}: ComponentProps<typeof ark.div>) => {
return (
<ark.div
data-slot="item-actions"
className={cn("flex items-center gap-2", className)}
{...props}
/>
);
};
export const ItemHeader = ({
className,
...props
}: ComponentProps<typeof ark.div>) => {
return (
<ark.div
data-slot="item-header"
className={cn(
"flex basis-full items-center justify-between gap-2",
className,
)}
{...props}
/>
);
};
export const ItemFooter = ({
className,
...props
}: ComponentProps<typeof ark.div>) => {
return (
<ark.div
data-slot="item-footer"
className={cn(
"flex basis-full items-center justify-between gap-2",
className,
)}
{...props}
/>
);
};
Update import aliases to match your project setup.
Usage
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemFooter,
ItemGroup,
ItemHeader,
ItemMedia,
ItemSeparator,
ItemTitle,
} from "@/components/ui/item"<ItemGroup>
<Item variant="outline">
<ItemMedia variant="icon">
<FileTextIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Report.pdf</ItemTitle>
<ItemDescription>Modified 2 hours ago</ItemDescription>
</ItemContent>
<ItemActions>
<Button size="sm" variant="ghost">Open</Button>
</ItemActions>
</Item>
</ItemGroup>Examples
Default
Report Q4.pdf
Modified 2 hours ago
Hero image.png
Modified yesterday
Intro reel.mp4
Modified last week
import { FileTextIcon, ImageIcon, VideoIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import {
Item,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemSeparator,
ItemTitle,
} from "@/components/ui/item";
const files = [
{
icon: FileTextIcon,
name: "Report Q4.pdf",
desc: "Modified 2 hours ago",
badge: "PDF",
},
{
icon: ImageIcon,
name: "Hero image.png",
desc: "Modified yesterday",
badge: "PNG",
},
{
icon: VideoIcon,
name: "Intro reel.mp4",
desc: "Modified last week",
badge: "MP4",
},
];
const ItemDemo = () => {
return (
<ItemGroup className="max-w-sm">
{files.map((file, i) => (
<>
{i > 0 && <ItemSeparator key={`sep-${file.name}`} />}
<Item key={file.name} variant="outline">
<ItemMedia variant="icon">
<file.icon />
</ItemMedia>
<ItemContent>
<ItemTitle>{file.name}</ItemTitle>
<ItemDescription>{file.desc}</ItemDescription>
</ItemContent>
<Badge variant="outline" className="ml-auto">
{file.badge}
</Badge>
</Item>
</>
))}
</ItemGroup>
);
};
export default ItemDemo;
Icon
Security Alert
New login detected from unknown device.
import { ShieldAlertIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemMedia,
ItemTitle,
} from "@/components/ui/item";
const ItemIcon = () => {
return (
<div className="flex w-full max-w-lg flex-col gap-6">
<Item variant="outline">
<ItemMedia variant="icon">
<ShieldAlertIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Security Alert</ItemTitle>
<ItemDescription>
New login detected from unknown device.
</ItemDescription>
</ItemContent>
<ItemActions>
<Button size="sm" variant="outline">
Review
</Button>
</ItemActions>
</Item>
</div>
);
};
export default ItemIcon;
Avatar
EREvil Rabbit
Last seen 5 months ago
ERNo Team Members
Invite your team to collaborate on this project.
import { PlusIcon } from "lucide-react";
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarImage,
} from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemMedia,
ItemTitle,
} from "@/components/ui/item";
const ItemAvatar = () => {
return (
<div className="flex w-full max-w-lg flex-col gap-6">
<Item variant="outline">
<ItemMedia>
<Avatar size="lg">
<AvatarImage src="https://github.com/evilrabbit.png" />
<AvatarFallback>ER</AvatarFallback>
</Avatar>
</ItemMedia>
<ItemContent>
<ItemTitle>Evil Rabbit</ItemTitle>
<ItemDescription>Last seen 5 months ago</ItemDescription>
</ItemContent>
<ItemActions>
<Button
size="icon-sm"
variant="outline"
className="rounded-full"
aria-label="Invite"
>
<PlusIcon />
</Button>
</ItemActions>
</Item>
<Item variant="outline">
<ItemMedia>
<AvatarGroup className="grayscale">
<Avatar className="hidden sm:flex">
<AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar className="hidden sm:flex">
<AvatarImage
src="https://github.com/maxleiter.png"
alt="@maxleiter"
/>
<AvatarFallback>ML</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage
src="https://github.com/evilrabbit.png"
alt="@evilrabbit"
/>
<AvatarFallback>ER</AvatarFallback>
</Avatar>
</AvatarGroup>
</ItemMedia>
<ItemContent>
<ItemTitle>No Team Members</ItemTitle>
<ItemDescription>
Invite your team to collaborate on this project.
</ItemDescription>
</ItemContent>
<ItemActions>
<Button size="sm" variant="outline">
Invite
</Button>
</ItemActions>
</Item>
</div>
);
};
export default ItemAvatar;
Image
import {
Item,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
} from "@/components/ui/item";
const music = [
{
title: "Midnight City Lights",
artist: "Neon Dreams",
album: "Electric Nights",
duration: "3:45",
},
{
title: "Coffee Shop Conversations",
artist: "The Morning Brew",
album: "Urban Stories",
duration: "4:05",
},
{
title: "Digital Rain",
artist: "Cyber Symphony",
album: "Binary Beats",
duration: "3:30",
},
];
const ItemImage = () => {
return (
<div className="flex w-full max-w-md flex-col gap-6">
<ItemGroup className="gap-4">
{music.map((song) => (
<Item key={song.title} variant="outline" role="listitem" asChild>
<a href="#">
<ItemMedia variant="image">
<img
src={`https://avatar.vercel.sh/${encodeURIComponent(song.title)}`}
alt={song.title}
width={32}
height={32}
className="object-cover grayscale"
/>
</ItemMedia>
<ItemContent>
<ItemTitle className="line-clamp-1">
{song.title} -{" "}
<span className="text-muted-foreground">{song.album}</span>
</ItemTitle>
<ItemDescription>{song.artist}</ItemDescription>
</ItemContent>
<ItemContent className="flex-none text-center">
<ItemDescription>{song.duration}</ItemDescription>
</ItemContent>
</a>
</Item>
))}
</ItemGroup>
</div>
);
};
export default ItemImage;
Group
Sshadcn
shadcn@vercel.com
Mmaxleiter
maxleiter@vercel.com
Eevilrabbit
evilrabbit@vercel.com
import { PlusIcon } from "lucide-react";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemTitle,
} from "@/components/ui/item";
const people = [
{
username: "shadcn",
avatar: "https://github.com/shadcn.png",
email: "shadcn@vercel.com",
},
{
username: "maxleiter",
avatar: "https://github.com/maxleiter.png",
email: "maxleiter@vercel.com",
},
{
username: "evilrabbit",
avatar: "https://github.com/evilrabbit.png",
email: "evilrabbit@vercel.com",
},
];
const ItemGroupDemo = () => {
return (
<ItemGroup className="max-w-sm">
{people.map((person) => (
<Item key={person.username} variant="outline">
<ItemMedia>
<Avatar>
<AvatarImage src={person.avatar} className="grayscale" />
<AvatarFallback>
{person.username.charAt(0).toUpperCase()}
</AvatarFallback>
</Avatar>
</ItemMedia>
<ItemContent className="gap-1">
<ItemTitle>{person.username}</ItemTitle>
<ItemDescription>{person.email}</ItemDescription>
</ItemContent>
<ItemActions>
<Button variant="ghost" size="icon" className="rounded-full">
<PlusIcon />
</Button>
</ItemActions>
</Item>
))}
</ItemGroup>
);
};
export default ItemGroupDemo;
Header
v0-1.5-sm
Everyday tasks and UI generation.
v0-1.5-lg
Advanced thinking or reasoning.
v0-2.0-mini
Open Source model for everyone.
import {
Item,
ItemContent,
ItemDescription,
ItemGroup,
ItemHeader,
ItemTitle,
} from "@/components/ui/item";
const models = [
{
name: "v0-1.5-sm",
description: "Everyday tasks and UI generation.",
image:
"https://images.unsplash.com/photo-1650804068570-7fb2e3dbf888?q=80&w=640&auto=format&fit=crop",
},
{
name: "v0-1.5-lg",
description: "Advanced thinking or reasoning.",
image:
"https://images.unsplash.com/photo-1610280777472-54133d004c8c?q=80&w=640&auto=format&fit=crop",
},
{
name: "v0-2.0-mini",
description: "Open Source model for everyone.",
image:
"https://images.unsplash.com/photo-1602146057681-08560aee8cde?q=80&w=640&auto=format&fit=crop",
},
];
const ItemHeaderDemo = () => {
return (
<div className="flex w-full max-w-xl flex-col gap-6">
<ItemGroup className="grid grid-cols-3 gap-4">
{models.map((model) => (
<Item key={model.name} variant="outline">
<ItemHeader>
<img
src={model.image}
alt={model.name}
width={128}
height={128}
className="aspect-square w-full rounded-sm object-cover"
/>
</ItemHeader>
<ItemContent>
<ItemTitle>{model.name}</ItemTitle>
<ItemDescription>{model.description}</ItemDescription>
</ItemContent>
</Item>
))}
</ItemGroup>
</div>
);
};
export default ItemHeaderDemo;
Link
Use asChild on Item to render as any element.
import { ChevronRightIcon, ExternalLinkIcon } from "lucide-react";
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemTitle,
} from "@/components/ui/item";
const ItemLink = () => {
return (
<div className="flex w-full max-w-md flex-col gap-4">
<Item asChild>
<a href="#">
<ItemContent>
<ItemTitle>Visit our documentation</ItemTitle>
<ItemDescription>
Learn how to get started with our components.
</ItemDescription>
</ItemContent>
<ItemActions>
<ChevronRightIcon className="size-4" />
</ItemActions>
</a>
</Item>
<Item variant="outline" asChild>
<a href="#" target="_blank" rel="noopener noreferrer">
<ItemContent>
<ItemTitle>External resource</ItemTitle>
<ItemDescription>
Opens in a new tab with security attributes.
</ItemDescription>
</ItemContent>
<ItemActions>
<ExternalLinkIcon className="size-4" />
</ItemActions>
</a>
</Item>
</div>
);
};
export default ItemLink;
Dropdown
Sshadcn
shadcn@vercel.com
Mmaxleiter
maxleiter@vercel.com
Eevilrabbit
evilrabbit@vercel.com
"use client";
import { ChevronDownIcon } from "lucide-react";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import {
Item,
ItemContent,
ItemDescription,
ItemMedia,
ItemTitle,
} from "@/components/ui/item";
import { Menu, MenuItem, MenuPopup, MenuTrigger } from "@/components/ui/menu";
const people = [
{
username: "shadcn",
avatar: "https://github.com/shadcn.png",
email: "shadcn@vercel.com",
},
{
username: "maxleiter",
avatar: "https://github.com/maxleiter.png",
email: "maxleiter@vercel.com",
},
{
username: "evilrabbit",
avatar: "https://github.com/evilrabbit.png",
email: "evilrabbit@vercel.com",
},
];
const ItemDropdown = () => {
return (
<Menu positioning={{ placement: "bottom-end" }}>
<MenuTrigger asChild>
<Button variant="outline">
Select <ChevronDownIcon />
</Button>
</MenuTrigger>
<MenuPopup className="w-48">
{people.map((person) => (
<MenuItem
key={person.username}
value={person.username}
className="p-0"
>
<Item size="xs" className="w-full">
<ItemMedia>
<Avatar size="sm">
<AvatarImage src={person.avatar} className="grayscale" />
<AvatarFallback>
{person.username.charAt(0).toUpperCase()}
</AvatarFallback>
</Avatar>
</ItemMedia>
<ItemContent className="gap-0">
<ItemTitle>{person.username}</ItemTitle>
<ItemDescription className="leading-none">
{person.email}
</ItemDescription>
</ItemContent>
</Item>
</MenuItem>
))}
</MenuPopup>
</Menu>
);
};
export default ItemDropdown;
Sizes
Default size
size="default"
Small size
size="sm"
import { UserIcon } from "lucide-react";
import {
Item,
ItemContent,
ItemDescription,
ItemGroup,
ItemMedia,
ItemSeparator,
ItemTitle,
} from "@/components/ui/item";
const ItemSizes = () => {
return (
<ItemGroup className="max-w-sm">
<Item variant="outline" size="default">
<ItemMedia variant="icon">
<UserIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Default size</ItemTitle>
<ItemDescription>size="default"</ItemDescription>
</ItemContent>
</Item>
<ItemSeparator />
<Item variant="outline" size="sm">
<ItemMedia variant="icon">
<UserIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Small size</ItemTitle>
<ItemDescription>size="sm"</ItemDescription>
</ItemContent>
</Item>
<ItemSeparator />
<Item variant="outline" size="xs">
<ItemMedia variant="icon">
<UserIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Extra small size</ItemTitle>
<ItemDescription>size="xs"</ItemDescription>
</ItemContent>
</Item>
</ItemGroup>
);
};
export default ItemSizes;
API reference
This component is an ark-cn composition. All props and DOM behavior are defined by the underlying ark factory elements.
Item variants
| Prop | Values | Default |
|---|---|---|
variant | default outline muted | default |
size | default sm xs | default |
ItemMedia variants
| Prop | Values | Default |
|---|---|---|
variant | default icon image | default |