Pagination¶
A shared pagination UI pattern for lists, cards, and similar content. Each screen opts into only the controls it needs.
List state (page index, page size, search, sort, filters) lives in URL query parameters only—not in localStorage or other client-only caches. Opening a URL without query parameters uses that screen’s defaults.
Layout¶
- Top row — controls on the left (
search→sort→filter→per page), special actions on the right (e.g. +). - Custom zone — optional slot below the top row (create forms, bulk actions, selection summary, etc.).
- Content — the paginated list or grid.
- Bottom row — range summary and page navigation.
Controls¶
Per page (default on)¶
Dropdown for how many items appear on each page. Enabled by default. The screen supplies allowed values; sensible defaults apply when none are configured (e.g. 24, 48, 96).
Search (optional)¶
Search field. Debounced updates write to the URL. An empty search omits the corresponding query parameter.
Sort (optional)¶
Dropdown listing sort terms. Each term cycles on click:
- First click — ASC (↑ before the label)
- Second click — DESC (↓ before the label)
- Third click — off (term removed)
When only one sort term exists, ASC and DESC toggle directly (no off state).
Active sort is encoded in the URL (e.g. name:asc, date:desc). Encoding is defined per screen but should be stable and shareable via links.
Filter (optional)¶
Dropdown of filter options, organized into groups.
- One choice per group — selecting an option in a group replaces any other choice in that group.
- All groups apply together — the active choice from every group is combined (typically AND on the server).
- Group labels — options belong to a group id (a default group, e.g.
main, is used when none is set). - If the screen has only the default group, list options without a group heading.
- If there are multiple groups, show each group under its heading (including the default group, with a generic label such as Main).
Example (file list):
| Group | Options |
|---|---|
| Status | All, Linked, Unlinked |
| Extension | All types, .jpg, .mp4, … |
Filter state is reflected in URL query parameters; shape is defined per screen.
Page navigation¶
Previous / next and numbered pages when there is more than one page. Summary line: start–end of total.
Special actions¶
Extra actions on the right of the top row:
| Control | Purpose |
|---|---|
| + | Toggles the custom zone (often a create or upload form). |
Custom zone¶
Slot for arbitrary content: create forms, bulk-action panels, selection summary, etc.
Visibility is controlled explicitly when needed (e.g. show while items are selected or a multi-step bulk action is in progress). By default, show the zone while the + create panel is open.
Common pattern: + reveals a create/upload form; bulk actions for the current selection appear in the same zone when the user has selected items.
Item selection (optional per screen)¶
Screens that support multi-select wire it in the content area. There is no separate “select mode” toggle—when selection is enabled, tiles or rows use selection behavior immediately.
| Interaction | Behavior |
|---|---|
| Click | Toggle one item |
| Shift+click | Range from the last anchor index |
| Double-click | Open the item (e.g. detail view); must not double-toggle selection |
When selection is not enabled for a screen, a single click opens the item (navigate, route, etc.).
Use a short delay on single-click (or equivalent) so double-click can open without firing two toggles. Cancel the pending single-click action on double-click.
Selection UI and bulk actions belong in the custom zone and/or inline on items. Keep the custom zone visible while bulk work is unfinished (e.g. chosen targets not yet applied).
Screen integration¶
Each paginated screen typically:
- Parses and builds URL query state for page, limit, search, sort, and filters.
- Loads data on the server (or API) with search, sort, filters, and
limit/offset(or equivalent). - Composes the shared pagination shell with only the controls that screen needs.
Do not add one-off controls to the shared pagination shell (e.g. no extra toolbar slots). Screen-specific actions belong in special actions or the custom zone only.