List Item

Data Display
Navigation

Versatile list item component for directory-style lists with icons, descriptions, and actions.

Preview

Interactive list with icons and navigation

Profile
Manage your profile settings
Notifications
Configure alerts and emails
Security
Password and two-factor auth

Basic List

Simple list items with title and description

Profile Settings
Update your personal information
Notifications
Configure how you receive alerts
Security
Manage your account security
Subscription
View and manage your plan

With End Content

List items with badges or status indicators

Messages
5 new
Tasks
3 pending
Favorites
12 items
Recent
Today

With Avatars

User list with avatars and role badges

SW
Sarah Wilson
sarah@example.com
Admin
JS
John Smith
john@example.com
Member
EC
Emily Chen
emily@example.com
Member

Sizes

Small, medium, and large list item sizes

Small

Small item
Compact size

Medium (default)

Medium item
Default size

Large

Large item
Spacious size

Props

Component API reference

ListItem

PropTypeDefaultDescription
title*ReactNode—Primary text content
descriptionReactNode—Secondary text below title
startContentReactNode—Icon or avatar at the start
endContentReactNode—Badge or content at the end
showChevronbooleanfalseShow navigation chevron
variant'default' | 'ghost' | 'bordered''default'Visual style variant
size'sm' | 'md' | 'lg''md'Size variant
onClick() => void—Click handler
disabledbooleanfalseDisable the item
classNamestring—Additional CSS classes

List

PropTypeDefaultDescription
children*ReactNode—ListItem components
dividedbooleanfalseAdd dividers between items
roundedbooleanfalseAdd border radius and border
classNamestring—Additional CSS classes

Usage

Import and implementation examples

import { ListItem, List } from '@/components/ui/list-item'
import { Avatar, AvatarFallback } from '@/components/ui/avatar'
import { Badge } from '@/components/ui/badge'
import { Settings, Mail } from 'lucide-react'

// Basic list
<List rounded divided>
  <ListItem title="Item 1" description="Description" />
  <ListItem title="Item 2" description="Description" />
</List>

// With icon
<ListItem
  title="Settings"
  description="Manage preferences"
  startContent={<Settings className="w-5 h-5" />}
/>

// Interactive with chevron
<ListItem
  title="Navigate"
  showChevron
  onClick={() => console.log('clicked')}
/>

// With end content
<ListItem
  title="Messages"
  endContent={<Badge>5 new</Badge>}
/>

// With avatar
<ListItem
  title="John Doe"
  description="john@example.com"
  startContent={
    <Avatar size="sm">
      <AvatarFallback>JD</AvatarFallback>
    </Avatar>
  }
/>

Features

Built-in functionality

  • Flexible content slots: Start, end, title, and description slots for custom content
  • Interactive states: Hover, focus, and active states with keyboard support
  • 3 size variants: Small, medium, and large sizing options
  • List wrapper: List component with dividers and rounded border options
  • Chevron indicator: Optional navigation chevron for clickable items
  • Text truncation: Automatic truncation for long content
  • Dark mode: Full dark mode support with adjusted colors

Accessibility

Accessibility considerations

ARIA Attributes

Interactive items use button roleDisabled state communicated via aria-disabledList structure uses semantic list markup

Keyboard Navigation

KeyAction
TabNavigate between list items
Enter / SpaceActivate clickable items

Notes

  • Focus indicators visible on all interactive items
  • Color contrast meets WCAG guidelines
  • Icons are decorative and hidden from screen readers

Related Components

CardAvatarBadgeMenu