Listing resources
Let users find, scan, and act on many resources — on an index page and in lists embedded in forms and detail pages.
A listing surface presents many resources so the user can scan them, tell them apart, and act. It covers the standalone index page as well as the smaller lists embedded inside forms (choosing related resources) and detail pages (sub-resources). Whatever the container, a list handles the same states rather than flashing a blank area.
| Tricks | Tags | ||||||
|---|---|---|---|---|---|---|---|
Noodlepets/noodle | kibble/discount-generic | Brisk | 2 tricks | Frisky | chaoticbeloved | ||
Sir Reginald Fluffington IIIpets/reginald-iii | kibble/premium-bamboo-cloud | Contemplative | 2 tricks | Napping | aristocrathigh-maintenance | ||
The Auditorpets/the-auditor | kibble/enterprise-bamboo | Ludicrous | 1 tricks | Under the weather | ominousdo-not-pet |
When to use this pattern
How to use the pattern
The index page
A standalone table of the resources, each row showing the few attributes that tell them apart and the row name leading to the detail page. A toolbar above the table carries a free-text search, per-column filter chips, sortable column headers, and the Create action; each row has an inline status toggle and a kebab of row actions. Search, filters, and sort narrow the set in place — they never blank the table — and the empty state repeats the Create call-to-action. It runs through loading, populated, empty, and error like any data-dependent view.† Reduce cognitive load † Think in states
Act on a row
The per-row kebab (⋯) holds the non-destructive actions — view details, copy ID — and a single delete. The inline status toggle starts or stops the resource straight from the row. Delete and the status toggle are the one place a failure surfaces as a toast: list actions act on a row, not a form.† Communicate side effects
A view backed by a request is never blank. Show a skeleton while it loads, the data once it arrives, a labelled empty state when there's nothing yet, and a recoverable error with a retry when the request fails — so the user always knows which situation they're in.† Think in states † Make errors recoverable
Select and bulk-delete
Optional Applies when users act on many resources at once.
Row checkboxes select across the filtered set; the toolbar then shows the count, a select-all, a clear, and a Delete N action behind a type-"delete" confirm. Partial failures report which rows didn't delete without losing the rest.† Make errors recoverable
Listing inside a form
Optional Applies when a form needs the user to pick related resources.
When a form needs the user to pick related resources, the list appears in a selectable mode — the surrounding form owns the selection; the list presents and reports it. Match the control to the data: a field that holds more than one value uses a multi-select list (checkbox rows); a field that holds one value whose options need supporting detail to choose between uses a card list; a one-value field with terse options uses a compact list. Past a length threshold the list paginates and gains a search box on its own; when the options carry facets worth narrowing by, it also shows filter chips — both surface only once the list is long enough to need them.† Keep actions near what they affect † Reduce cognitive load
Listing inside a detail page
Optional Applies when a detail page shows referenced or sub-resources.
A detail page shows referenced or sub-resources as the same three lists, read-only — the same multi-select / card / compact choice as in a form, made by the same data question, just without the selection affordances. Each row links to that resource's own detail page, and the list handles loading, empty, and error like a full index.† Think in states † Keep actions near what they affect
Behavior
This pattern delivers one goal: find, scan, tell apart, and act on many resources — without the surface ever flashing blank. The checks below are how you verify an implementation delivers it.
- Loading —
Show a skeleton in the list's shape; never a blank area.
- Populated —
Show the few attributes that distinguish each item.
- Empty —
Explain why it's empty and offer the next step. Distinct from the error state.
- Error —
Show what failed and a retry; keep the rest of the page usable.
- Filtering —
Search and facet chips narrow rows in place; a multi-value chip matches rows holding any selected value. Clearing chips restores the full set. No matches shows a "no matching" state, not the empty state.
- Sorting —
A sortable header cycles unsorted → ascending → descending; the active direction is announced.
- Row menu —
The kebab opens view / copy ID / delete. Copy writes the clipboard with a success toast; each item is a single click target.
- Status toggle —
The inline toggle starts/stops the row. On success the cell updates; on failure it reverts and an error toasts.
- Delete —
A confirm dialog names the resource; on success the list refreshes with a success toast, on failure the row stays and an error toasts — nothing disappears optimistically.
- Bulk deleteOptional —
Selecting rows reveals a count, select-all, clear, and Delete N behind a type-"delete" confirm. Partial failures list the rows that didn't delete.
- Inside a formOptional —
Embedded in a form, the list runs in selectable mode; the surrounding form owns the selection and the list only presents and reports it.
- Inside a detail pageOptional —
Sub-resources render as a small embedded list with the same loading / empty / error handling as a full index.
- PaginationOptional —
When rows exceed the page size, a pager appears; paging works both directions and the page size is adjustable.
- Sibling tabsOptional —
Adjacent non-CRUD views (a setup guide, usage) are tabs under the same header — one route, not separate sibling routes.
- Accessibility —
Real list/table semantics convey structure and item count; row and item actions are reachable and operable by keyboard. Sort direction and selection state are announced, not signalled by a visual cue alone, and loading and empty states are announced rather than conveyed by layout.
Content & copy
Columns and labels stay terse; empty and count text follow the style guide. (See the UX text style guide.)
- Empty text says why and what next: "No pets yet. Create one to get started."
- Column headers are sentence case and terse.
- Abbreviate large counts: "33K results".
- A bare "No data" or an empty container with no explanation.
- Title Case headers or restating the resource name in every column.
- Spelling out large numbers ("33,000 results found").
Accessibility
- Use real list or table semantics so structure and item count are conveyed.
- Row and item actions are reachable and operable by keyboard.
- When sorting or selection exist, announce the current state, not just a visual cue.
- Loading and empty states are announced, not signalled by layout alone.
Related patterns
- Resource detail — where a row leads.
- Creating a resource — the Create action's target.
- Editing a resource — changing a resource a row points at.