Resource list

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Use a resource list to keep one resource's title, secondary information, status, selection, and actions in one row. Build it from the existing List slots.
• Keep title links and per-row actions separate.
• The Checkbox carries the selection semantics. List.Item.selected only adds visual emphasis to the whole surface.
• Default padding is 12px vertical and 16px horizontal, with 8px between rows. Long identifiers wrap.

• Don't turn an li into a fake clickable button or a listbox. Use the title link and per-row actions.
• Don't nest a Checkbox or Menu inside the title link. Keep each in its own slot.
• Don't convey results through status color alone. Name each status in text.
• Don't silently clear selections hidden by a search. Retain the hidden IDs.
• Don't leave the scope of select-all ambiguous. Make clear whether it covers the visible rows or the full dataset.
• Don't expect the primitives to handle server requests, permissions, page navigation, or the validity of selected IDs. The product owns them.

Anatomy

FilterBar → result summary + optional visible-selection controls → List.Root(ul) → Item(li) → Checkbox + Content(Title link + Description) + Actions(StatusBadge + Menu)

Keyboard and accessibility

• Tab visits the selection checkbox, the title link, and the actions menu, in that order.
• Menus use Base UI's arrow keys, Enter, and Escape. Closing a menu returns focus to that row's trigger.
• Space toggles a Checkbox. Links keep the browser's open-in-new-tab and back behavior.
• Clearing a selection or recovering from an error returns focus to the remaining search input.
• Loading, error, restricted access, first-use empty, and no search results each get their own message.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { List, Checkbox, StatusBadge, Menu } from '@surflane/ui'

<List.Root aria-label='Registered resources'>
  {resources.map((resource) => (
    <List.Item key={resource.id} selected={selected.has(resource.id)}>
      <Checkbox.Root
        aria-label={`Select ${resource.name}`}
        checked={selected.has(resource.id)}
        onCheckedChange={(value) => select(resource.id, value)}
      >
        <Checkbox.Indicator />
      </Checkbox.Root>
      <List.Content>
        <List.Title>
          <a href={resource.href}>{resource.name}</a>
        </List.Title>
        <List.Description>{resource.description}</List.Description>
      </List.Content>
      <List.Actions>
        <StatusBadge tone='success'>Ready</StatusBadge>
        <Menu.Root>
          <Menu.Trigger aria-label={`Actions for ${resource.name}`}>
            Actions
          </Menu.Trigger>
          <Menu.Portal>
            <Menu.Content>
              <Menu.Item onClick={() => inspect(resource.id)}>
                Inspect
              </Menu.Item>
            </Menu.Content>
          </Menu.Portal>
        </Menu.Root>
      </List.Actions>
    </List.Item>
  ))}
</List.Root>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens