List

A grouped list of rows wrapped in a single card with dividers between items.

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.

Basic

Profile

Your personal information.

Notifications

Manage what you hear from us.

Settings New

Tune the app to your preferences.

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.

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.

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.