Creative Tim UICreative Tim UI

Shadcn List

PreviousNext

A list component that displays a collection of items in a structured format, perfect for navigation menus, settings panels, and data displays.

  • Inbox
  • Trash
  • Settings
import { List, ListItem } from "@/components/ui/list"

export function ListDemo() {
  return (
    <List>
      <ListItem>Inbox</ListItem>
      <ListItem>Trash</ListItem>
      <ListItem>Settings</ListItem>
    </List>
  )
}

Installation

pnpm dlx @creative-tim/ui@latest add list

Usage

import { List, ListItem } from "@/components/ui/list"
<List>
  <ListItem>Item 1</ListItem>
  <ListItem>Item 2</ListItem>
  <ListItem>Item 3</ListItem>
</List>

Examples

List with Icon

A list component with icons positioned at the start of each item, providing visual cues and enhancing the user interface.

  • Inbox
  • Trash
  • Settings
import { Mail, Settings, Trash2 } from "lucide-react"

import { List, ListItem, ListItemStart } from "@/components/ui/list"

export function ListWithIcon() {
  return (
    <List>
      <ListItem>
        <ListItemStart>
          <Mail className="h-5 w-5" />
        </ListItemStart>
        Inbox
      </ListItem>
      <ListItem>
        <ListItemStart>
          <Trash2 className="h-5 w-5" />
        </ListItemStart>
        Trash
      </ListItem>
      <ListItem>
        <ListItemStart>
          <Settings className="h-5 w-5" />
        </ListItemStart>
        Settings
      </ListItem>
    </List>
  )
}

List with Avatar

A list component with avatars displayed at the start of each item, perfect for displaying user profiles, team members, or contact information.

  • A

    Alex Andrew

    Software Engineer @ Creative Tim UI

  • A

    Alexander

    Backend Developer @ Creative Tim UI

  • E

    Emma Willever

    UI/UX Designer @ Creative Tim UI

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import { List, ListItem, ListItemStart } from "@/components/ui/list"

interface ListItemProps {
  img: string
  title: string
  description: string
}

function ListItemWithAvatar({ img, title, description }: ListItemProps) {
  return (
    <ListItem>
      <ListItemStart>
        <Avatar>
          <AvatarImage src={img} alt="profile-picture" />
          <AvatarFallback>{title.charAt(0)}</AvatarFallback>
        </Avatar>
      </ListItemStart>
      <div>
        <p className="font-semibold">{title}</p>
        <p className="text-foreground text-sm">{description}</p>
      </div>
    </ListItem>
  )
}

export function ListWithAvatar() {
  return (
    <List>
      <ListItemWithAvatar
        img="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
        title="Alex Andrew"
        description="Software Engineer @ Creative Tim UI"
      />
      <ListItemWithAvatar
        img="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
        title="Alexander"
        description="Backend Developer @ Creative Tim UI"
      />
      <ListItemWithAvatar
        img="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
        title="Emma Willever"
        description="UI/UX Designer @ Creative Tim UI"
      />
    </List>
  )
}

List with Badge

A list component with badges displayed at the end of each item, useful for showing counts, notifications, or status indicators.

  • Inbox
    14
  • Trash
    40
  • Settings
import { Mail, Settings, Trash2 } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import {
  List,
  ListItem,
  ListItemEnd,
  ListItemStart,
} from "@/components/ui/list"

export function ListWithBadge() {
  return (
    <List>
      <ListItem>
        <ListItemStart>
          <Mail className="h-5 w-5" />
        </ListItemStart>
        Inbox
        <ListItemEnd>
          <Badge variant="secondary" size="sm">
            14
          </Badge>
        </ListItemEnd>
      </ListItem>
      <ListItem>
        <ListItemStart>
          <Trash2 className="h-5 w-5" />
        </ListItemStart>
        Trash
        <ListItemEnd>
          <Badge variant="secondary" size="sm">
            40
          </Badge>
        </ListItemEnd>
      </ListItem>
      <ListItem>
        <ListItemStart>
          <Settings className="h-5 w-5" />
        </ListItemStart>
        Settings
      </ListItem>
    </List>
  )
}

List with Link

A list component where items are rendered as links, perfect for navigation menus or clickable lists.

import { List, ListItem } from "@/components/ui/list"

export function ListWithLink() {
  return (
    <List>
      <ListItem asChild>
        <a href="#list-with-link">Inbox</a>
      </ListItem>
      <ListItem asChild>
        <a href="#list-with-link">Trash</a>
      </ListItem>
      <ListItem asChild>
        <a href="#list-with-link">Settings</a>
      </ListItem>
    </List>
  )
}

List with Disabled Item

A list component with disabled items that cannot be interacted with, useful for displaying unavailable options or temporarily restricting user interaction.

  • Inbox
  • Trash
  • Settings
import { List, ListItem } from "@/components/ui/list"

export function ListWithDisabledItem() {
  return (
    <List>
      <ListItem disabled>Inbox</ListItem>
      <ListItem>Trash</ListItem>
      <ListItem>Settings</ListItem>
    </List>
  )
}

List with Selected Item

A list component with selectable items that can be highlighted when clicked, demonstrating how to manage selected state.

  • Inbox
  • Trash
  • Settings
"use client"

import * as React from "react"

import { List, ListItem } from "@/components/ui/list"

export function ListWithSelectedItem() {
  const [selected, setSelected] = React.useState("inbox")

  return (
    <List>
      <ListItem
        selected={selected === "inbox"}
        onClick={() => setSelected("inbox")}
      >
        Inbox
      </ListItem>
      <ListItem
        selected={selected === "trash"}
        onClick={() => setSelected("trash")}
      >
        Trash
      </ListItem>
      <ListItem
        selected={selected === "settings"}
        onClick={() => setSelected("settings")}
      >
        Settings
      </ListItem>
    </List>
  )
}

Custom List Styles

A list component with custom styling that demonstrates how to personalize the appearance to match your brand or design requirements, such as custom hover colors and transitions.

  • Inbox
    14
  • Trash
    40
  • Settings
import { Mail, Settings, Trash2 } from "lucide-react"

import { cn } from "@/lib/utils"
import { Badge } from "@/components/ui/badge"
import {
  List,
  ListItem,
  ListItemEnd,
  ListItemStart,
} from "@/components/ui/list"

export function ListCustomStyles() {
  return (
    <List>
      <ListItem
        className={cn(
          "group hover:bg-neutral-900 hover:text-white focus:bg-neutral-900 focus:text-white"
        )}
      >
        <ListItemStart>
          <Mail className="h-5 w-5" />
        </ListItemStart>
        Inbox
        <ListItemEnd>
          <Badge
            variant="secondary"
            size="sm"
            className={cn(
              "transition-colors duration-300 group-hover:bg-white"
            )}
          >
            14
          </Badge>
        </ListItemEnd>
      </ListItem>
      <ListItem
        className={cn(
          "group hover:bg-neutral-900 hover:text-white focus:bg-neutral-900 focus:text-white"
        )}
      >
        <ListItemStart>
          <Trash2 className="h-5 w-5" />
        </ListItemStart>
        Trash
        <ListItemEnd>
          <Badge
            variant="secondary"
            size="sm"
            className={cn(
              "transition-colors duration-300 group-hover:bg-white"
            )}
          >
            40
          </Badge>
        </ListItemEnd>
      </ListItem>
      <ListItem
        className={cn(
          "group hover:bg-neutral-900 hover:text-white focus:bg-neutral-900 focus:text-white"
        )}
      >
        <ListItemStart>
          <Settings className="h-5 w-5" />
        </ListItemStart>
        Settings
      </ListItem>
    </List>
  )
}

Props

The list component is built using native HTML elements with enhanced styling and accepts the following props:

List

PropTypeDefaultDescription
classNamestring-Additional CSS classes to apply to the list
childrenReactNode-The list items to display

ListItem

PropTypeDefaultDescription
asChildbooleanfalseWhen true, merges props with the child element
selectedbooleanfalseWhen true, applies selected styling to the item
disabledbooleanfalseWhen true, prevents the user from interacting with the item
classNamestring-Additional CSS classes to apply to the item
childrenReactNode-The content to display in the item
onClickfunction-Event handler called when the item is clicked

ListItemStart

PropTypeDefaultDescription
classNamestring-Additional CSS classes to apply
childrenReactNode-The content to display at the start of the item

ListItemEnd

PropTypeDefaultDescription
classNamestring-Additional CSS classes to apply
childrenReactNode-The content to display at the end of the item

Accessibility

The list component follows accessibility best practices:

  • Uses proper semantic HTML (<ul> and <li> elements)
  • Supports keyboard navigation (Tab to navigate, Enter/Space to activate)
  • Focus states are clearly visible for keyboard users
  • Disabled state is properly communicated to assistive technologies
  • Selected state is visually and programmatically indicated
  • Maintains proper semantic HTML structure
  • Works well with screen readers

Best Practices

  • Use lists to organize related items in a structured format
  • Provide clear labels and descriptions for list items
  • Use icons or avatars to enhance visual clarity
  • Consider using badges to show counts or status indicators
  • Use disabled state to show unavailable options without hiding them
  • Ensure sufficient contrast between text and background colors
  • Test keyboard navigation and screen reader compatibility
  • Use selected state to indicate the current active item
  • Group related items together for better organization
  • Consider using links for navigation lists

The list component provides a clean and accessible way to display collections of items. It's ideal for navigation menus, settings panels, user lists, data displays, and any interface where items need to be organized in a structured format.