List

A grouped list of rows with dividers between items. The default card variant adds a border and rounded corners; use variant="rail" when the parent pane owns the surrounding chrome. Rail lists keep a bottom border so the final row still has a visible boundary.

ListItem is a static row. Use ListItemButton for click handlers and ListItemLink for typesafe navigation — both ship with hover, focus, and cursor styles built in.

Props

Prop	Values	Default	Notes
`as`	`'div'` \| `'ul'`	`'div'`	`ul` renders real list semantics; wrap each row in your own `<li>`.
`variant`	`'card'` \| `'rail'`	`'card'`	`card` adds a border and rounded corners; `rail` keeps only a bottom border.

Prefer as="ul". An explicit ARIA role replaces the implicit one, so the div form has to put role="listitem" on each row — which costs that row its own button or link role. Rows read the form from List and drop the role automatically under as="ul", so nothing to set per item:

<List as="ul" variant="rail">
  {rows.map((row) => (
    <li key={row.id}>
      <ListItemButton selected={row.id === selectedId}>{row.title}</ListItemButton>
    </li>
  ))}
</List>

Basic

Profile

Your personal information.

Notifications

Manage what you hear from us.

SettingsNew

Tune the app to your preferences.

import {
  Badge,
  HStack,
  List,
  ListItem,
  ListItemContent,
  ListItemDescription,
  ListItemMedia,
  ListItemTitle,
} from "@vesyl/ui-next";
import { Bell, Settings, User } from "lucide-react";

export default function ListBasic() {
  return (
    <HStack justify="center">
      <List className="max-w-md">
        <ListItem>
          <ListItemMedia>
            <User />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Profile</ListItemTitle>
            <ListItemDescription>Your personal information.</ListItemDescription>
          </ListItemContent>
        </ListItem>
        <ListItem>
          <ListItemMedia>
            <Bell />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Notifications</ListItemTitle>
            <ListItemDescription>Manage what you hear from us.</ListItemDescription>
          </ListItemContent>
        </ListItem>
        <ListItem>
          <ListItemMedia>
            <Settings />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>
              Settings
              <Badge variant="subtle" colorPalette="orange">
                New
              </Badge>
            </ListItemTitle>
            <ListItemDescription>Tune the app to your preferences.</ListItemDescription>
          </ListItemContent>
        </ListItem>
      </List>
    </HStack>
  );
}

With Actions

Rows that own a control (switch, checkbox, trailing button) stay as static ListItems — never nest a button inside a clickable row.

Email notifications

Receive a summary every morning.

Push notifications

Get pinged on this device.

import {
  HStack,
  List,
  ListItem,
  ListItemActions,
  ListItemContent,
  ListItemDescription,
  ListItemMedia,
  ListItemTitle,
  Switch,
} from "@vesyl/ui-next";
import { Bell, Mail } from "lucide-react";

export default function ListWithActions() {
  return (
    <HStack justify="center">
      <List className="max-w-md">
        <ListItem>
          <ListItemMedia>
            <Mail />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Email notifications</ListItemTitle>
            <ListItemDescription>Receive a summary every morning.</ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <Switch defaultChecked />
          </ListItemActions>
        </ListItem>
        <ListItem>
          <ListItemMedia>
            <Bell />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Push notifications</ListItemTitle>
            <ListItemDescription>Get pinged on this device.</ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <Switch />
          </ListItemActions>
        </ListItem>
      </List>
    </HStack>
  );
}

As Links

ListItemLink wraps ListItemButton with TanStack Router’s createLink. Pass to, params, search directly — fully typed against the consumer’s route tree. Always pass dynamic segments through params (e.g. to="/orgs/$orgSlug" params={{ orgSlug }}) rather than interpolating into the path string — interpolation skips type checking and silently breaks when a route changes.

import {
  RouterProvider,
  createMemoryHistory,
  createRootRoute,
  createRoute,
  createRouter,
} from '@tanstack/react-router'
import {
  HStack,
  List,
  ListItemActions,
  ListItemContent,
  ListItemDescription,
  ListItemLink,
  ListItemMedia,
  ListItemTitle,
} from '@vesyl/ui-next'
import { ChevronRight, CreditCard, Settings } from 'lucide-react'

const orgSlug = 'acme'

function ListExample() {
  return (
    <HStack justify="center">
      <List className="max-w-md">
        <ListItemLink to="/orgs/$orgSlug/settings" params={{ orgSlug }}>
          <ListItemMedia>
            <Settings />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Workspace settings</ListItemTitle>
            <ListItemDescription>Members, integrations, security.</ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <ChevronRight className="text-muted-foreground" />
          </ListItemActions>
        </ListItemLink>
        <ListItemLink to="/orgs/$orgSlug/billing" params={{ orgSlug }}>
          <ListItemMedia>
            <CreditCard />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Billing</ListItemTitle>
            <ListItemDescription>Plan, payment method, invoices.</ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <ChevronRight className="text-muted-foreground" />
          </ListItemActions>
        </ListItemLink>
      </List>
    </HStack>
  )
}

const rootRoute = createRootRoute({ component: ListExample })
const settingsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/orgs/$orgSlug/settings',
})
const billingRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/orgs/$orgSlug/billing',
})
const routeTree = rootRoute.addChildren([settingsRoute, billingRoute])

const router = createRouter({
  routeTree,
  history: createMemoryHistory({ initialEntries: ['/'] }),
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

export default function ListAsLinks() {
  return <RouterProvider router={router} />
}

As Buttons

Use ListItemButton when the entire row should fire an onClick instead of navigate.

import {
  HStack,
  List,
  ListItemActions,
  ListItemButton,
  ListItemContent,
  ListItemDescription,
  ListItemMedia,
  ListItemTitle,
} from "@vesyl/ui-next";
import { ChevronRight, User } from "lucide-react";

export default function ListAsButtons() {
  return (
    <HStack justify="center">
      <List className="max-w-md">
        <ListItemButton onClick={() => {}}>
          <ListItemMedia>
            <User />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Switch account</ListItemTitle>
            <ListItemDescription>Sign in as a different user.</ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <ChevronRight className="text-muted-foreground" />
          </ListItemActions>
        </ListItemButton>
      </List>
    </HStack>
  );
}

Inactive

inactive sinks the row (muted in light, subtle in dark — muted is a lift on dark rows) and fades its content. Trailing ListItemActions stay full strength so enable/disable (or similar) still read. Use interactive on a static ListItem when the row is clickable but owns nested buttons — ListItemButton cannot wrap other buttons. size="sm" tightens vertical padding.

Hold international

Holds order when country is not US

Singles

Disabled — Adds tag "Singles" when product SKUs match

import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
  HStack,
  List,
  ListItem,
  ListItemActions,
  ListItemContent,
  ListItemDescription,
  ListItemTitle,
} from "@vesyl/ui-next";
import { Copy, Ellipsis, Pause, Play, Trash2 } from "lucide-react";

export default function ListInactive() {
  return (
    <HStack justify="center">
      <List className="max-w-md">
        <ListItem interactive>
          <ListItemContent>
            <ListItemTitle>Hold international</ListItemTitle>
            <ListItemDescription>Holds order when country is not US</ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <DropdownMenu>
              <DropdownMenuTrigger
                render={
                  <Button variant="ghost" size="icon" aria-label="Actions">
                    <Ellipsis />
                  </Button>
                }
              />
              <DropdownMenuContent align="end">
                <DropdownMenuItem>
                  <Pause /> Disable
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <Copy /> Duplicate
                </DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem variant="destructive">
                  <Trash2 /> Delete
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
          </ListItemActions>
        </ListItem>
        <ListItem interactive inactive>
          <ListItemContent>
            <ListItemTitle>Singles</ListItemTitle>
            <ListItemDescription>Disabled — Adds tag "Singles" when product SKUs match</ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <DropdownMenu>
              <DropdownMenuTrigger
                render={
                  <Button variant="ghost" size="icon" aria-label="Actions">
                    <Ellipsis />
                  </Button>
                }
              />
              <DropdownMenuContent align="end">
                <DropdownMenuItem>
                  <Play /> Enable
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <Copy /> Duplicate
                </DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem variant="destructive">
                  <Trash2 /> Delete
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
          </ListItemActions>
        </ListItem>
      </List>
    </HStack>
  );
}

Selected

Use selected for the current item in a list-to-detail flow. The default selection is neutral. selectionVariant="accent" gives interactive rows a faint accent hover and a stronger accent tint when selected.

import {
  HStack,
  List,
  ListItemButton,
  ListItemContent,
  ListItemDescription,
  ListItemTitle,
} from "@vesyl/ui-next";

export default function ListSelected() {
  return (
    <HStack justify="center">
      <List className="max-w-md">
        <ListItemButton selected selectionVariant="accent">
          <ListItemContent>
            <ListItemTitle>Hold international orders</ListItemTitle>
            <ListItemDescription>Currently open in the detail panel</ListItemDescription>
          </ListItemContent>
        </ListItemButton>
        <ListItemButton>
          <ListItemContent>
            <ListItemTitle>Apply fragile tag</ListItemTitle>
            <ListItemDescription>Adds a tag when fragile products are present</ListItemDescription>
          </ListItemContent>
        </ListItemButton>
      </List>
    </HStack>
  );
}

With Trailing Button

Some rows have a primary action instead of a link or a switch.

Delete account

Permanently remove this account and all its data.

import {
  Button,
  HStack,
  List,
  ListItem,
  ListItemActions,
  ListItemContent,
  ListItemDescription,
  ListItemMedia,
  ListItemTitle,
} from "@vesyl/ui-next";
import { User } from "lucide-react";

export default function ListWithTrailingButton() {
  return (
    <HStack justify="center">
      <List className="max-w-md">
        <ListItem>
          <ListItemMedia>
            <User />
          </ListItemMedia>
          <ListItemContent>
            <ListItemTitle>Delete account</ListItemTitle>
            <ListItemDescription>
              Permanently remove this account and all its data.
            </ListItemDescription>
          </ListItemContent>
          <ListItemActions>
            <Button variant="outline" size="sm">
              Delete
            </Button>
          </ListItemActions>
        </ListItem>
      </List>
    </HStack>
  );
}