use-selection

Generic single- or multi-select state for lists, tables, and grids.


Package	`@vizejs/composable/use-selection`
Own the source	`vize lib pull composable:use-selection`
Runtime exports	`useSelection`
Gzip budget	1280 B

Usage

import { useSelection } from "@vizejs/composable/use-selection";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useSelection`	state	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—

API

`useSelection`

Generic single- or multi-select state for lists, tables, and grids. Keys (from getKey, the item itself by default) identify items, so the selection survives items being replaced. multiple: true switches the selected type to an array; max, required, and isSelectable constrain changes, and extendTo implements shift-click ranges from the anchor in display order. Synchronous state: SSR-safe and nothing to dispose.

function useSelection<Item, Key = Item, const Multiple extends boolean = false>( options: UseSelectionOptions<Item, Key, Multiple>, ): Selection<Item, Key, Multiple>

const rows = useSelection({ items: users, multiple: true, getKey: (user) => user.id });
rows.toggle(user);
rows.extendTo(other); // shift-click

`useSelection`

function useSelection( options: UseSelectionOptions<unknown, unknown, boolean>, ): Selection<unknown, unknown, boolean>

Types

`UseSelectionOptions`

Options for useSelection.

Member	Type	Description
`items`	`MaybeRefOrGetter<readonly Item[]>`	Selectable items, in display order. Reactive.
`multiple`?	`Multiple`	Allow several selected items.
`getKey`?	`(item: Item) => Key`	Stable identity of an item, for example its id. Keys survive item objects being replaced (refetches, immutable updates).
`initial`?	`readonly Key[]`	Keys selected initially.
`max`?	`number`	Maximum number of selected items in multiple mode; selecting beyond it is refused.
`required`?	`boolean`	Refuse to deselect the last selected item.
`isSelectable`?	`(item: Item) => boolean`	Veto selecting an item (for example disabled rows).

`Selection`

Selection state and commands returned by useSelection.

Member	Type	Description
`selectedKeys`	`Readonly<ShallowRef<readonly Key[]>>`	Selected keys in selection order.
`selected`	`ComputedRef<Multiple extends true ? Item[] : Item \| undefined>`	Selected items in `items` order: an array in multiple mode, the single item (or `undefined`) otherwise. Keys whose item is currently absent are kept but not listed.
`count`	`ComputedRef<number>`	Number of selected keys.
`isAllSelected`	`ComputedRef<boolean>`	Whether every selectable item is selected (multiple mode).
`isIndeterminate`	`ComputedRef<boolean>`	Whether some but not all selectable items are selected (tri-state checkboxes).
`anchor`	`Readonly<ShallowRef<Key \| undefined>>`	Item that anchors range selection (the last explicitly selected one).
`isSelected`	`(item: Item) => boolean`	Whether `item` is selected.
`select`	`(item: Item) => boolean`	Select `item` (replacing the selection in single mode).
`deselect`	`(item: Item) => boolean`	Deselect `item`.
`toggle`	`(item: Item) => boolean`	Toggle `item`.
`selectOnly`	`(item: Item) => boolean`	Select exactly `item`.
`extendTo`	`(item: Item) => boolean`	Select every item between the anchor and `item` inclusive (shift-click); in single mode this selects `item`.
`selectAll`	`() => void`	Select every selectable item, up to `max` (multiple mode).
`clear`	`() => void`	Clear the selection (ignores `required`).