AddThisFeature
Sign in

Selection State Pattern

Make selected rows, cards, and objects look and behave the same everywhere.

moderate User Experience

What it adds

One selection model and one visual treatment shared by tables, card grids, lists, and canvas surfaces.

What your agent is told to do

5
  1. 1

    Find every surface that already has a notion of selection — table rows, card grids, file lists, canvas objects, option pickers — and reduce them to a single selection model rather than the several that have accumulated.

  2. 2

    Hold selection as state keyed by stable record identity, never by row index or position in the DOM, so sorting, filtering, and paging cannot move the highlight onto a different record.

  3. 3

    Support click to select, modifier click to add and remove, and shift click to extend a range, and make each of those reachable from the keyboard as well as the pointer.

  4. 4

    Always show how many items are selected and give a single control that clears the selection, placed where the user can find it without scrolling back to the top of a long list.

  5. 5

    Do not express selection with a background tint alone. A row can be hovered, focused, and selected at once, and one tint cannot carry three meanings — pair selection with a persistent marker such as a checkbox or a border, and leave the focus ring itself to the Hover Active Focus Checklist.

Edge cases it handles

7
  • Hover, keyboard focus, and selection frequently land on the same row at the same time; all three must stay readable together and none may visually cancel another.
  • Range selection needs a defined anchor. The anchor must move on a plain click and be preserved across a shift click, or extending a range a second time selects the wrong span.
  • Forced-colours and high contrast modes discard background colours, so selection must also be carried by a border, an outline, or a control that genuinely exists in the accessibility tree.
  • Re-sorting, filtering, or paging must keep the same records selected, including records that have scrolled out of view, rather than keeping the same positions selected.
  • Select-all needs a stated scope: everything on this page, or everything matching the current filter. Conflating the two ends with a bulk action applied to records the user never saw.
  • A selected record deleted by someone else, or moved out of the filter, must drop out of the selection quietly and the count must update.
  • Screen readers need the selected state exposed through the control's role rather than implied by colour; a selected row that reads identically to an unselected one is unusable.

Definition of done

9
  • A single selection model backs tables, grids, lists, and canvas surfaces.
  • Selection is keyed to record identity and survives sorting, filtering, and paging.
  • Single, additive, and range selection all work with the pointer and from the keyboard.
  • Hover, focus, and selected states remain distinguishable when applied to the same element.
  • Selection stays visible under forced-colours and high contrast settings.
  • The selected count is visible and can be cleared in one action.
  • Select-all states its scope explicitly before it is applied.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.