# useSelection

> A React selection hook for lists, tables and grids: single or multiple, Shift-click ranges, and select all with an indeterminate state.

- Type: React hook (Hooks & Utilities)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add use-selection`
- Docs: https://wingo-ui.com/components/use-selection

## Interaction

Tick customers in the list; hold Shift and tick another to select everything between them. The header checkbox shows the indeterminate state and selects or clears all (the archived customer stays unselectable). Switch to single mode to pick one at a time; clicking it again clears it.

## Installation

```bash
npx wingo-ui@latest add use-selection
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/use-selection` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `hooks/use-selection.ts`

Wingo UI dependencies (installed automatically):

- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))

## Usage

```tsx
import { useSelection } from "@/hooks/use-selection"

const clients = [
  { id: "c1", name: "Northwind Tech LLC" },
  { id: "c2", name: "Summit Logistics Inc." },
  { id: "c3", name: "Greenleaf Pharmacy" },
]

export function ClientPicker() {
  const selection = useSelection({ keys: clients.map((c) => c.id) })
  return (
    <ul>
      {clients.map((client) => (
        <li key={client.id}>
          <label>
            <input
              type="checkbox"
              checked={selection.isSelected(client.id)}
              onClick={(event) => selection.handleSelect(client.id, event)}
              readOnly
            />
            {client.name}
          </label>
        </li>
      ))}
    </ul>
  )
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode?` | `"single" \| "multiple"` | `"multiple"` | single keeps at most one key (radio-like rows); multiple is for bulk actions. |
| `allowDeselect?` | `boolean` | `true` | Single mode: selecting the selected key again clears the selection. |
| `keys` | `readonly string[]` |  | Every selectable key in display order. Shift ranges walk this order; select all takes all of them. |
| `value / defaultValue / onValueChange?` | `string[]` |  | Controlled or uncontrolled through useControllableState. onValueChange gets the keys in display order. |
| `disabledKeys?` | `readonly string[]` |  | Keys that cannot be selected: toggle ignores them, ranges and select all skip them. |
| `useSelection (result)?` | `{ selected; isSelected(key); isDisabled(key); toggle(key, { range?, additive? }); handleSelect(key, event); select; deselect; selectRange(from, to); selectAll; clear; setSelected(keys); toggleAll; allSelected; someSelected; checkedState: boolean \| "indeterminate"; count }` |  | handleSelect reads shiftKey from the click or key event (pass it straight from onClick / onCheckedChange's event). checkedState feeds a header Checkbox. Rendering stays yours: aria-selected / aria-checked and data-selected on the rows. |

## Parts

### SelectionMode (type)

"single" | "multiple".

### UseSelectionOptions (type)

The options object: keys, mode, value, defaultValue, onValueChange, disabledKeys and allowDeselect.

### SelectionModifiers (type)

The second argument of toggle: { range?: boolean; additive?: boolean }.

### UseSelectionResult (type)

The return value: selected keys, checks, actions, allSelected, someSelected, checkedState, count and handleSelect.

## Examples

- **Bulk actions**: Select invoices (Shift-click for a range) and the header turns into an action bar with the total.
- **Single choice cards**: mode="single" with allowDeselect off: plan cards that always keep one selected.

## See also

- [Checkbox](https://wingo-ui.com/components/checkbox) ([Markdown](https://wingo-ui.com/components/checkbox.md))
- [Data Table](https://wingo-ui.com/components/data-table) ([Markdown](https://wingo-ui.com/components/data-table.md))
- [Listbox](https://wingo-ui.com/components/listbox) ([Markdown](https://wingo-ui.com/components/listbox.md))
- [Toolbar](https://wingo-ui.com/components/toolbar) ([Markdown](https://wingo-ui.com/components/toolbar.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))

---

Canonical: https://wingo-ui.com/components/use-selection
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt