List React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

List is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import List from @/components/ui/list.

import { Archive, Bell, Globe, Trash2, User } from "lucide-react"
import { List, type ListGroupData } from "@/components/ui/list"
import { Switch } from "@/components/ui/switch"

export function Settings({ onDelete }: { onDelete: (id: string) => void }) {
  const groups: ListGroupData[] = [
    {
      id: "account",
      label: "Account",
      items: [
        { id: "profile", title: "Profile", description: "emma.carter@northwind.app", icon: <User />, href: "/settings/profile" },
        { id: "notifications", title: "Notifications", icon: <Bell />, trailing: <Switch defaultChecked aria-label="Notifications" /> },
        { id: "language", title: "Language", icon: <Globe />, value: "English", href: "/settings/language" },
      ],
    },
    {
      id: "clients",
      label: "Recent clients",
      footer: "Swipe a row to the left to archive it.",
      items: [
        {
          id: "c01",
          title: "Acme Corp",
          description: "San Francisco · Nathan Price",
          avatar: { name: "Acme Corp" },
          value: "$12,480.00",
          swipe: {
            trailing: [
              { id: "archive", label: "Archive", icon: <Archive />, tone: "neutral", destructive: true, onSelect: () => onDelete("c01") },
              { id: "delete", label: "Delete", icon: <Trash2 />, tone: "danger", destructive: true, onSelect: () => onDelete("c01") },
            ],
          },
        },
      ],
    },
  ]
  return <List groups={groups} />
}

// parts, for rows the items API does not cover (same file, same look):
// ListRoot takes every appearance and behavior prop of List (variant, size, dividers, radius, tone, color,
//   selectionMode + selection props, sortable + onReorder, swipeable / swipeWithMouse / fullSwipe, onAction(id),
//   labels, classNames) plus keys / disabledKeys (read from the rows when left out); role list, or listbox;
// ListGroup { label, footer, refreshing } holds the variant's surface and animates rows in and out;
// ListItem takes every ListItemData field as a prop plus selected / onSelectedChange (standalone rows),
//   asChild (your router Link as the row), interactive and size; children replace the generated content;
// content parts: ListItemLeading, ListItemIcon { tone, color, variant }, ListItemContent, ListItemTitle,
//   ListItemDescription, ListItemTrailing (sits above the stretched pressable, so controls stay clickable);
// ListItemActions { items: MenuEntry[], open, onOpenChange, title, label } is the ⋯ menu (a sheet on phones);
// ListSortableHandle { label } is the grip of a sortable row (renders nothing outside a sortable list);
// SwipeActions { leading, trailing, disabled, swipeWithMouse, fullSwipe, onOpenChange, onRemovingChange }
//   wraps any row; DEFAULT_LIST_LABELS holds the English strings to spread a translation over
import { Star } from "lucide-react"
import {
  ListRoot, ListGroup, ListItem, ListItemLeading, ListItemIcon, ListItemContent, ListItemTitle,
  ListItemDescription, ListItemTrailing, ListItemActions,
} from "@/components/ui/list"

export function Favorites({ rows }: { rows: { id: string; name: string; city: string; total: string }[] }) {
  return (
    <ListRoot variant="separated" size="lg" aria-label="Favorite clients">
      <ListGroup label="Favorites">
        {rows.map((row) => (
          <ListItem key={row.id} id={row.id} title={row.name} href={`/clients/${row.id}`}>
            <ListItemLeading>
              <ListItemIcon tone="warning" variant="solid">
                <Star />
              </ListItemIcon>
            </ListItemLeading>
            <ListItemContent>
              <ListItemTitle>{row.name}</ListItemTitle>
              <ListItemDescription>{row.city}</ListItemDescription>
            </ListItemContent>
            <ListItemTrailing className="tabular-nums">{row.total}</ListItemTrailing>
            <ListItemActions items={[{ id: "open", label: "Open", href: `/clients/${row.id}` }]} />
          </ListItem>
        ))}
      </ListGroup>
    </ListRoot>
  )
}

Props

• items
  ListItemData[]

  The rows: { id, title, textValue?, description?, leading?, icon?, iconTone?, iconColor?, avatar?: { src?, name, status? }, trailing?, value?, badge?, href?, onSelect?, disabled?, tone?: "neutral" | "danger" | "brand", chevron?, actions?: MenuEntry[], swipe?: { leading?: SwipeAction[], trailing?: SwipeAction[] } }. trailing may hold controls (a Switch); the row then gets a stretched pressable so nothing nests in a button.

• groups
  ListGroupData[]

  { id, label?, footer?, items }[]: grouped rows with a small header and a footer note (iOS settings). Replaces items; sorting stays within a group.

• variantdefault "inset"
  "inset" | "plain" | "separated" | "card"

  inset: the iOS grouped panel (a raised surface with hairlines); plain: full-bleed rows with hairlines, no container; separated: each row its own raised panel with an 8px gap; card: one flat gray tile with hairlines.

• sizedefault "md"
  "sm" | "md" | "lg"

  Row height 44 / 56 / 64px with matching padding, avatars (32 / 40 / 48px) and icon tiles. Every size keeps a 44px target on touch.

• dividersdefault "inset"
  "full" | "inset" | "none"

  Hairlines between rows. inset starts them at the text, after the icon or avatar (iOS); full spans the row.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg"

  Corner radius of the panel (inset, card) or of each row (separated): 0 / 12 / 16 / 24px. First and last rows follow it.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The selection color: the checkbox fill, the check mark and the highlight tint.

• colordefault ""
  string

  Any CSS color for the selection; replaces the tone.

• iconVariantdefault "soft"
  "soft" | "solid" | "plain"

  Icon tiles: a soft tint (gray, or the icon tone), a solid fill (the iOS settings look, with iconColor), or the bare icon.

• selectionIndicatordefault "auto"
  "auto" | "checkbox" | "check" | "highlight"

  How a selected row shows: a leading checkbox, a trailing check (iOS pickers) or the row fill alone (with aria-selected). auto is a checkbox for multiple and a check for single.

• actionsVisibilitydefault "hover"
  "hover" | "always"

  The ⋯ row menu button: revealed on hover and focus with a mouse (always visible on touch), or always shown.

• selectionModedefault "none"
  "none" | "single" | "multiple"

  none: navigation rows in the Tab order (labelled groups become labelled lists). single / multiple: a listbox with roving focus, Space to toggle, Shift ranges and Ctrl / Cmd + A (through useSelection); give it an aria-label. Inside an option the ⋯ button is pointer-only and Shift + F10 opens the menu.

• selectedKeys
  string[]

  Controlled selection, in display order. Pair with onSelectedKeysChange.

• defaultSelectedKeysdefault "[]"
  string[]

  Selection while uncontrolled.

• onSelectedKeysChange
  (keys: string[]) => void

  Fires with the selected ids in display order.

• loadingdefault false
  boolean

  Skeleton rows in the row shape (a leading circle when the rows have avatars or icons) inside the same container, with aria-busy.

• refreshingdefault false
  boolean

  Keeps the rows and runs a thin indeterminate bar along the top edge of the first group (in the selection tone), with aria-busy. For pull to refresh and background reloads.

• skeletonCountdefault 4
  number

  How many skeleton rows show while loading.

• emptyState
  ReactNode

  Shown when there are no rows; defaults to <EmptyState preset="empty" size="sm" title={labels.empty} />.

• error
  ReactNode

  Replaces the rows with the error EmptyState, this text as its description.

• onRetry
  () => (void | Promise<unknown>)

  Adds Try again to the error state; a returned promise shows it loading.

• showChevrondefault true
  boolean

  Navigation rows (href or onSelect) end in a chevron. item.chevron overrides it per row.

• sortabledefault false
  boolean

  Drag handles (dnd-kit): mouse after 8px, touch after a 250ms press, keyboard with Space and arrows, plus Alt + Up / Down on a focused row or grip. The lifted row floats with a shadow and a slight tilt; groups reorder within themselves.

• onReorder
  (ids: string[], move: { id: string; from: number; to: number }) => void

  Fires after a drop or an Alt + Arrow move with the new order of that group. The list keeps the new order until you pass new items.

• swipeabledefault true
  boolean

  Rows with swipe actions can be swiped on touch. Off: the actions stay in the ⋯ menu and the long-press sheet.

• swipeWithMousedefault false
  boolean

  Mouse drags swipe too. Off, desktop uses the ⋯ menu and right click, so text and clicks behave as usual.

• fullSwipedefault true
  boolean

  Swiping past 60% of the row runs the outermost action (iOS swipe to delete), with a haptic tick when it arms.

• onAction
  (id: string, item: ListItemData) => void

  Row activation (click, tap, Enter), after the item's own onSelect.

• getActions
  (item: ListItemData) => (MenuEntry[] | undefined)

  Row menu entries per item, instead of item.actions. The menu also lists the row's swipe actions.

• labels
  Partial<ListLabels>

  English defaults (DEFAULT_LIST_LABELS): actions "More actions for {item}", select, dragHandle "Drag to reorder {item}", pickedUp, moved "{item} moved to position {n} of {total}.", dropped, cancelled, empty, loading, sheetTitle, cancel.

• classNames
  Partial<Record<ListSlot, string>>

  Extra classes per part: group, header, items, footer, item, row, select, leading, icon, body, content, title, description, trailing, value, chevron, actions, handle, swipe, swipeAction, overlay, refreshing, empty.

• className
  string

  Classes for the root. Override the swipe surface with [--list-bg:var(--card)] when the list sits on another surface.

Parts

FAQ

Used in

More React table and list components