Lists

Rows of comparable content that extend into tables.

Double line

Media, title and description in a 72px row: 40px of content and 16px of padding top and bottom. Set actions when the row holds controls, so it skips the hover fill.

Avery Chen
avery@northwind.io
Jordan Lee
jordan@northwind.io
Riley Gupta
riley@northwind.io

import { useState } from "react";
import {
  Button,
  ChevronDownIcon,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
  Entity,
  EntityAside,
  EntityContent,
  EntityMedia,
  List,
  ListItem,
  MoreVerticalIcon,
  cn,
  controlSurfaceClass,
} from "@smallest-inc/ui";

const permissions = ["Admin", "Member", "Guest"];

const initialMembers = [
  { name: "Avery Chen", email: "avery@northwind.io", permission: "Admin" },
  { name: "Jordan Lee", email: "jordan@northwind.io", permission: "Member" },
  { name: "Riley Gupta", email: "riley@northwind.io", permission: "Member" },
];

export default function ListDoubleLine() {
  const [members, setMembers] = useState(initialMembers);

  function setPermission(name: string, permission: string) {
    setMembers((current) => current.map((member) => (member.name === name ? { ...member, permission } : member)));
  }

  return (
    <div className="w-full">
      <List>
        {members.map((member) => (
          <ListItem key={member.name} actions>
            <Entity>
              <EntityMedia />
              <EntityContent title={member.name} description={member.email} />
              <EntityAside>
                <DropdownMenu>
                  <DropdownMenuTrigger
                    render={
                      <button
                        type="button"
                        aria-label={`Permission for ${member.name}`}
                        className={cn(
                          controlSurfaceClass("md", "primary"),
                          "inline-flex w-32 cursor-pointer items-center justify-between pr-2 pl-3 text-left"
                        )}
                      />
                    }
                  >
                    <span className="min-w-0 truncate">{member.permission}</span>
                    <ChevronDownIcon className="size-4 text-fg-secondary" />
                  </DropdownMenuTrigger>
                  <DropdownMenuContent align="end" className="w-32">
                    <DropdownMenuRadioGroup
                      value={member.permission}
                      onValueChange={(value) => setPermission(member.name, value as string)}
                    >
                      {permissions.map((permission) => (
                        <DropdownMenuRadioItem key={permission} value={permission}>
                          {permission}
                        </DropdownMenuRadioItem>
                      ))}
                    </DropdownMenuRadioGroup>
                  </DropdownMenuContent>
                </DropdownMenu>
                <DropdownMenu>
                  <DropdownMenuTrigger
                    render={<Button iconOnly variant="transparent" aria-label={`More actions for ${member.name}`} />}
                  >
                    <MoreVerticalIcon />
                  </DropdownMenuTrigger>
                  <DropdownMenuContent align="end" className="w-44">
                    <DropdownMenuItem>Resend invite</DropdownMenuItem>
                    <DropdownMenuItem variant="danger">Remove from workspace</DropdownMenuItem>
                  </DropdownMenuContent>
                </DropdownMenu>
              </EntityAside>
            </Entity>
          </ListItem>
        ))}
      </List>
    </div>
  );
}

Single line

A 52px row with a title only. Density is inferred from EntityContent; set density="compact" to be explicit and use EntityMedia size="sm".

Nova Sales Assistant
+1 (415) 555-0198
Pulse Support Agent
+1 (212) 555-0147
Orbit Retention Bot
+44 20 7946 0958

import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
  Entity,
  EntityAside,
  EntityContent,
  EntityMedia,
  List,
  ListItem,
  MoreVerticalIcon,
} from "@smallest-inc/ui";

const agents = [
  { name: "Nova Sales Assistant", number: "+1 (415) 555-0198" },
  { name: "Pulse Support Agent", number: "+1 (212) 555-0147" },
  { name: "Orbit Retention Bot", number: "+44 20 7946 0958" },
];

export default function ListSingleLine() {
  return (
    <div className="w-full">
      <List>
        {agents.map((agent) => (
          <ListItem key={agent.name} actions density="compact">
            <Entity>
              <EntityMedia size="sm" />
              <EntityContent title={agent.name} />
              <EntityAside>
                <span className="text-sm text-fg-secondary">{agent.number}</span>
                <DropdownMenu>
                  <DropdownMenuTrigger
                    render={
                      <Button iconOnly variant="transparent" size="xs" aria-label={`More actions for ${agent.name}`} />
                    }
                  >
                    <MoreVerticalIcon />
                  </DropdownMenuTrigger>
                  <DropdownMenuContent align="end" className="w-44">
                    <DropdownMenuItem>Change number</DropdownMenuItem>
                    <DropdownMenuItem variant="danger">Unlink number</DropdownMenuItem>
                  </DropdownMenuContent>
                </DropdownMenu>
              </EntityAside>
            </Entity>
          </ListItem>
        ))}
      </List>
    </div>
  );
}

Trailing text

Rows with only text on the right pick up a neutral-50 hover fill.

Nova Sales Assistant
+1 (415) 555-0198
1m 05s
Pulse Support Agent
+1 (212) 555-0147
4m 18s
Orbit Retention Bot
+44 20 7946 0958
0m 55s

import { Entity, EntityAside, EntityContent, List, ListItem } from "@smallest-inc/ui";

const calls = [
  { agent: "Nova Sales Assistant", caller: "+1 (415) 555-0198", duration: "1m 05s" },
  { agent: "Pulse Support Agent", caller: "+1 (212) 555-0147", duration: "4m 18s" },
  { agent: "Orbit Retention Bot", caller: "+44 20 7946 0958", duration: "0m 55s" },
];

export default function ListTrailingText() {
  return (
    <div className="w-full">
      <List>
        {calls.map((call) => (
          <ListItem key={call.caller}>
            <Entity>
              <EntityContent title={call.agent} description={call.caller} />
              <EntityAside>
                <span className="text-sm text-fg-secondary tabular-nums">{call.duration}</span>
              </EntityAside>
            </Entity>
          </ListItem>
        ))}
      </List>
    </div>
  );
}

Checkbox

Set checkbox to put a checkbox on the right edge. Clicking anywhere on the row toggles it.

Emily
American English, warm and conversational
Arjun
Indian English, calm and clear
Sofía
Latin American Spanish, bright and upbeat

import { useState } from "react";
import { Entity, EntityContent, EntityMedia, List, ListItem } from "@smallest-inc/ui";

const voices = [
  { name: "Emily", description: "American English, warm and conversational" },
  { name: "Arjun", description: "Indian English, calm and clear" },
  { name: "Sofía", description: "Latin American Spanish, bright and upbeat" },
];

export default function ListCheckbox() {
  const [selected, setSelected] = useState<string[]>(["Emily"]);

  return (
    <div className="w-full">
      <List>
        {voices.map((voice) => (
          <ListItem
            key={voice.name}
            checkbox
            checked={selected.includes(voice.name)}
            onCheckedChange={(checked) =>
              setSelected((current) =>
                checked ? [...current, voice.name] : current.filter((name) => name !== voice.name)
              )
            }
            checkboxLabel={`Select ${voice.name}`}
          >
            <Entity>
              <EntityMedia />
              <EntityContent title={voice.name} description={voice.description} />
            </Entity>
          </ListItem>
        ))}
      </List>
    </div>
  );
}

Trailing controls

The trailing slot takes an input, select, multi-select or button without forcing a single-line row to double height.

Agent name
Voice
Languages
Phone numbers

import { useState } from "react";
import {
  Button,
  Entity,
  EntityContent,
  Input,
  List,
  ListItem,
  MultiSelect,
  MultiSelectContent,
  MultiSelectItem,
  MultiSelectTrigger,
  MultiSelectValue,
  PlusIcon,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const voices = ["Emily", "Arjun", "Sofía"];
const languages = ["English", "Hindi", "Spanish"];

export default function ListTrailingControls() {
  const [selectedLanguages, setSelectedLanguages] = useState<string[]>(["English", "Hindi"]);

  return (
    <div className="w-full">
      <List>
        <ListItem trailing={<Input aria-label="Agent name" defaultValue="Nova Sales Assistant" className="w-52" />}>
          <Entity>
            <EntityContent title="Agent name" />
          </Entity>
        </ListItem>
        <ListItem
          trailing={
            <Select items={voices.map((value) => ({ label: value, value }))} defaultValue="Emily">
              <SelectTrigger aria-label="Voice" className="w-40">
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                {voices.map((voice) => (
                  <SelectItem key={voice} value={voice}>
                    {voice}
                  </SelectItem>
                ))}
              </SelectContent>
            </Select>
          }
        >
          <Entity>
            <EntityContent title="Voice" />
          </Entity>
        </ListItem>
        <ListItem
          trailing={
            <MultiSelect
              items={languages.map((value) => ({ label: value, value }))}
              value={selectedLanguages}
              onValueChange={setSelectedLanguages}
            >
              <MultiSelectTrigger aria-label="Languages" className="w-40">
                <MultiSelectValue plural="languages" />
              </MultiSelectTrigger>
              <MultiSelectContent>
                {languages.map((language) => (
                  <MultiSelectItem key={language} value={language}>
                    {language}
                  </MultiSelectItem>
                ))}
              </MultiSelectContent>
            </MultiSelect>
          }
        >
          <Entity>
            <EntityContent title="Languages" />
          </Entity>
        </ListItem>
        <ListItem
          trailing={
            <Button size="sm" variant="secondary">
              <PlusIcon />
              Add number
            </Button>
          }
        >
          <Entity>
            <EntityContent title="Phone numbers" />
          </Entity>
        </ListItem>
      </List>
    </div>
  );
}

Stacked trailing controls

Set trailingLayout="stacked" when one setting owns several fields. The row grows to fit them.

Webhook endpoints
Call events go to the primary URL, then the fallback.

import { Entity, EntityContent, Input, List, ListItem } from "@smallest-inc/ui";

export default function ListStackedTrailing() {
  return (
    <div className="w-full">
      <List>
        <ListItem
          trailingLayout="stacked"
          trailing={
            <>
              <Input aria-label="Primary webhook URL" placeholder="https://hooks.example.com/calls" className="w-64" />
              <Input aria-label="Fallback webhook URL" placeholder="Fallback URL" className="w-64" />
            </>
          }
        >
          <Entity>
            <EntityContent title="Webhook endpoints" description="Call events go to the primary URL, then the fallback." />
          </Entity>
        </ListItem>
      </List>
    </div>
  );
}

Nested

Set nested on a ListItem and put a ListNested inside it. The row becomes a disclosure with a chevron; children indent 8px per level.

- Orbit Retention Bot
  Live
- Helios Billing Support
  Live
- Vega Feedback Collector
  Live

import {
  Entity,
  EntityAside,
  EntityContent,
  EntityMedia,
  List,
  ListItem,
  ListNested,
} from "@smallest-inc/ui";

const campaigns = [
  {
    name: "Q3 renewals",
    summary: "3 agents",
    agents: ["Orbit Retention Bot", "Helios Billing Support", "Vega Feedback Collector"],
  },
  {
    name: "Inbound sales",
    summary: "2 agents",
    agents: ["Nova Sales Assistant", "Zephyr Lead Qualifier"],
  },
  {
    name: "Onboarding",
    summary: "1 agent",
    agents: ["Atlas Onboarding Guide"],
  },
];

export default function ListNestedExample() {
  return (
    <div className="w-full">
      <List>
        {campaigns.map((campaign) => (
          <ListItem key={campaign.name} nested defaultOpen={campaign.name === "Q3 renewals"}>
            <Entity>
              <EntityContent title={campaign.name} description={campaign.summary} />
            </Entity>
            <ListNested>
              {campaign.agents.map((agent) => (
                <ListItem key={agent} density="compact">
                  <Entity>
                    <EntityMedia size="sm" />
                    <EntityContent title={agent} />
                    <EntityAside>
                      <span className="text-sm text-fg-secondary">Live</span>
                    </EntityAside>
                  </Entity>
                </ListItem>
              ))}
            </ListNested>
          </ListItem>
        ))}
      </List>
    </div>
  );
}

Columns

ListColumns wraps the list in a Frame with a 1px inset. ListHeader holds the column labels in the well, aligned to the row content.

Phone numberProviderAgent

+1 (415) 555-0198
TwilioNova Sales Assistant
+1 (212) 555-0147
PlivoPulse Support Agent
+44 20 7946 0958
TwilioOrbit Retention Bot

import {
  Entity,
  EntityAside,
  EntityContent,
  EntityMedia,
  List,
  ListColumns,
  ListHeader,
  ListItem,
} from "@smallest-inc/ui";

const numbers = [
  { number: "+1 (415) 555-0198", provider: "Twilio", agent: "Nova Sales Assistant" },
  { number: "+1 (212) 555-0147", provider: "Plivo", agent: "Pulse Support Agent" },
  { number: "+44 20 7946 0958", provider: "Twilio", agent: "Orbit Retention Bot" },
];

export default function ListWithColumns() {
  return (
    <div className="w-full">
      <ListColumns>
        <ListHeader weight="medium">
          <span className="min-w-0 flex-1">Phone number</span>
          <span className="flex items-center gap-12">
            <span className="w-24">Provider</span>
            <span className="w-48">Agent</span>
          </span>
        </ListHeader>
        <List>
          {numbers.map((row) => (
            <ListItem key={row.number} density="compact">
              <Entity>
                <EntityMedia size="sm" />
                <EntityContent title={row.number} />
                <EntityAside className="gap-12 text-sm text-fg-secondary">
                  <span className="w-24">{row.provider}</span>
                  <span className="w-48 truncate">{row.agent}</span>
                </EntityAside>
              </Entity>
            </ListItem>
          ))}
        </List>
      </ListColumns>
    </div>
  );
}

Nested columns

Nested rows work inside ListColumns; keep child columns aligned to the header.

TeamRole

- Avery Chen
  avery@northwind.io
  Admin
- Jordan Lee
  jordan@northwind.io
  Member

import {
  Entity,
  EntityAside,
  EntityContent,
  EntityMedia,
  List,
  ListColumns,
  ListHeader,
  ListItem,
  ListNested,
} from "@smallest-inc/ui";

const teams = [
  {
    name: "Support",
    summary: "2 members",
    members: [
      { name: "Avery Chen", email: "avery@northwind.io", role: "Admin" },
      { name: "Jordan Lee", email: "jordan@northwind.io", role: "Member" },
    ],
  },
  {
    name: "Sales",
    summary: "1 member",
    members: [{ name: "Riley Gupta", email: "riley@northwind.io", role: "Member" }],
  },
];

export default function ListNestedColumns() {
  return (
    <div className="w-full">
      <ListColumns>
        <ListHeader weight="medium">
          <span className="min-w-0 flex-1">Team</span>
          <span className="w-24">Role</span>
        </ListHeader>
        <List>
          {teams.map((team) => (
            <ListItem key={team.name} nested defaultOpen={team.name === "Support"}>
              <Entity>
                <EntityContent title={team.name} description={team.summary} />
              </Entity>
              <ListNested>
                {team.members.map((member) => (
                  <ListItem key={member.email}>
                    <Entity>
                      <EntityMedia />
                      <EntityContent title={member.name} description={member.email} />
                      <EntityAside>
                        <span className="w-24 text-sm text-fg-secondary">{member.role}</span>
                      </EntityAside>
                    </Entity>
                  </ListItem>
                ))}
              </ListNested>
            </ListItem>
          ))}
        </List>
      </ListColumns>
    </div>
  );
}

Sortable columns

ListHeaderColumn with sortable cycles none, ascending and descending on each click. Sort the rows yourself; cycleListSortDirection returns the next direction.

Nova Sales Assistant
Inbound sales
1,450
Pulse Support Agent
Customer support
3,210
Atlas Onboarding Guide
Customer onboarding
640

import { useState } from "react";
import {
  Entity,
  EntityAside,
  EntityContent,
  List,
  ListColumns,
  ListHeader,
  ListHeaderColumn,
  ListItem,
  cycleListSortDirection,
  type ListSortDirection,
} from "@smallest-inc/ui";

type SortKey = "agent" | "calls";

const agents = [
  { agent: "Nova Sales Assistant", description: "Inbound sales", calls: 1450 },
  { agent: "Pulse Support Agent", description: "Customer support", calls: 3210 },
  { agent: "Atlas Onboarding Guide", description: "Customer onboarding", calls: 640 },
];

export default function ListSortable() {
  const [sort, setSort] = useState<{ key: SortKey; direction: ListSortDirection }>({ key: "agent", direction: "none" });

  function toggle(key: SortKey) {
    setSort((current) => ({
      key,
      direction: cycleListSortDirection(current.key === key ? current.direction : "none"),
    }));
  }

  const rows =
    sort.direction === "none"
      ? agents
      : [...agents].sort((a, b) => {
          const order = sort.key === "agent" ? a.agent.localeCompare(b.agent) : a.calls - b.calls;
          return sort.direction === "asc" ? order : -order;
        });

  const directionFor = (key: SortKey) => (sort.key === key ? sort.direction : "none");

  return (
    <div className="w-full">
      <ListColumns>
        <ListHeader weight="medium" className="justify-between gap-6">
          <ListHeaderColumn sortable sortDirection={directionFor("agent")} onSort={() => toggle("agent")}>
            Agent
          </ListHeaderColumn>
          <ListHeaderColumn sortable sortDirection={directionFor("calls")} onSort={() => toggle("calls")}>
            Calls
          </ListHeaderColumn>
        </ListHeader>
        <List>
          {rows.map((row) => (
            <ListItem key={row.agent}>
              <Entity>
                <EntityContent title={row.agent} description={row.description} />
                <EntityAside>
                  <span className="text-sm text-fg-secondary tabular-nums">{row.calls.toLocaleString("en-US")}</span>
                </EntityAside>
              </Entity>
            </ListItem>
          ))}
        </List>
      </ListColumns>
    </div>
  );
}

Page size

Set pageSize to reveal rows you already have in batches, with a Load more button under the list.

Nova Sales Assistant
CALL-4506
1m 05s
Zephyr Lead Qualifier
CALL-4507
2m 42s
Pulse Support Agent
CALL-4508
4m 18s

import { Entity, EntityAside, EntityContent, List, ListItem } from "@smallest-inc/ui";

const calls = [
  { id: "CALL-4506", agent: "Nova Sales Assistant", duration: "1m 05s" },
  { id: "CALL-4507", agent: "Zephyr Lead Qualifier", duration: "2m 42s" },
  { id: "CALL-4508", agent: "Pulse Support Agent", duration: "4m 18s" },
  { id: "CALL-4509", agent: "Orbit Retention Bot", duration: "0m 55s" },
  { id: "CALL-4510", agent: "Atlas Onboarding Guide", duration: "5m 33s" },
  { id: "CALL-4511", agent: "Vega Feedback Collector", duration: "3m 07s" },
  { id: "CALL-4512", agent: "Lyra Appointment Setter", duration: "1m 48s" },
];

export default function ListPageSize() {
  return (
    <div className="w-full">
      <List pageSize={3}>
        {calls.map((call) => (
          <ListItem key={call.id}>
            <Entity>
              <EntityContent title={call.agent} description={call.id} />
              <EntityAside>
                <span className="text-sm text-fg-secondary tabular-nums">{call.duration}</span>
              </EntityAside>
            </Entity>
          </ListItem>
        ))}
      </List>
    </div>
  );
}

Load more

Pass loadMore to fetch the next page. The button shows a spinner while isLoadingMore is true. Set autoLoadCount to load that many pages on scroll before the button takes over.

Nova Sales Assistant
12 turns
T-1024
Zephyr Lead Qualifier
8 turns
T-1023
Pulse Support Agent
21 turns
T-1022

import { useState } from "react";
import { Entity, EntityAside, EntityContent, List, ListItem } from "@smallest-inc/ui";

const allTranscripts = [
  { id: "T-1024", agent: "Nova Sales Assistant", turns: 12 },
  { id: "T-1023", agent: "Zephyr Lead Qualifier", turns: 8 },
  { id: "T-1022", agent: "Pulse Support Agent", turns: 21 },
  { id: "T-1021", agent: "Orbit Retention Bot", turns: 6 },
  { id: "T-1020", agent: "Atlas Onboarding Guide", turns: 15 },
  { id: "T-1019", agent: "Vega Feedback Collector", turns: 9 },
  { id: "T-1018", agent: "Lyra Appointment Setter", turns: 11 },
];

export default function ListLoadMore() {
  const [transcripts, setTranscripts] = useState(() => allTranscripts.slice(0, 3));
  const [loading, setLoading] = useState(false);

  function loadMore() {
    setLoading(true);
    // Stands in for a network request.
    window.setTimeout(() => {
      setTranscripts((current) => allTranscripts.slice(0, current.length + 3));
      setLoading(false);
    }, 800);
  }

  return (
    <div className="w-full">
      <List
        loadMore={{
          hasMore: transcripts.length < allTranscripts.length,
          onLoadMore: loadMore,
          isLoadingMore: loading,
          buttonLabel: "Load more transcripts",
        }}
      >
        {transcripts.map((transcript) => (
          <ListItem key={transcript.id}>
            <Entity>
              <EntityContent title={transcript.agent} description={`${transcript.turns} turns`} />
              <EntityAside>
                <span className="text-sm text-fg-secondary">{transcript.id}</span>
              </EntityAside>
            </Entity>
          </ListItem>
        ))}
      </List>
    </div>
  );
}

Best practices

When to use

Use for a vertical set of comparable rows read top to bottom: members, phone numbers, transcripts, settings.
Use Table when people compare values across several named columns; use List when each row is one identity plus one or two values.
Use ListColumns when rows need column labels. Labels sit in the well; don't add a section title there.

Behavior

Single-line rows (density="compact") are 52px with EntityMedia size="sm". Double-line rows are 72px with default 40px media. Density is inferred from EntityContent; set it explicitly when the content is custom.
Rows without controls get a neutral-50 hover. Set actions when a row holds a menu, select or input; trailing and checkbox rows opt out of the hover fill automatically.
Menus opened from a row keep that row highlighted until they close. Use DropdownMenu for row menus so this works.
Use checkbox for multi-select rows: the checkbox sits on the right edge and clicking anywhere on the row toggles it. Pass checkboxLabel naming the row, e.g. "Select Emily".
Use trailingLayout="stacked" only when one setting owns several fields; the row grows to fit.
Use nested ListItem with ListNested for hierarchy (campaign → agents). Keep flat rows for peers. Open the first group with defaultOpen when it is the likely target.
Use pageSize to reveal rows you already have in batches. Use loadMore for server pages, and set isLoadingMore while the request is in flight. autoLoadCount loads that many pages on scroll before the button takes over.
ListHeaderColumn sortable only renders the state; sort the rows yourself and advance with cycleListSortDirection (none → asc → desc).

Content

Titles are the identity (agent name, phone number); descriptions are one line of context (email, purpose, duration).
Keep trailing text short and tabular: durations, counts, roles.

Accessibility

Name every icon-only row action with its target: "More actions for Avery Chen".
Sortable headers are buttons with aria-sort; keep the visible label the same as the column name.

PreviousLabel NextMiddle Truncate