useGroup

Commons
stable

Provides a reactive selection group that manages a list of registered items, single or multiple selection, mandatory enforcement, and max limit. Pairs with useGroupItem — the parent calls useGroup, each child calls useGroupItem.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

useGroup provides state via Vue provide/inject. The injectKey symbol must be shared between the parent and all children — export it from a dedicated const file to avoid symbol identity mismatches across module boundaries.

Consumed interfaces

IGroupProps
IGroupItemProps
IGroupProvide
IGroupItemProvide

API

Parameters

Input parameters accepted by this composable.

props
required
IGroupProps
Props of the parent group component: modelValue, multiple, mandatory, max, selectedClass, disabled.
injectKey
required
InjectionKey<IGroupProvide>
Unique injection key used to link the group provider with its children. Must be the same symbol in both useGroup and useGroupItem calls.
required
boolean
true
useGroupItem only — when false, the composable returns null silently instead of throwing if no matching group injection is found.

API

Return values

Properties and methods exposed by the composable return object.

register
Registers a child item into the group at the correct DOM order.
unregister
Removes a child item from the group (called automatically on unmount).
selected
Reactive list of internal IDs that are currently selected.
select
Toggles or forces the selection state of a specific item, respecting mandatory and max constraints.
prev
Moves selection to the previous non-disabled item (wraps around).
next
Moves selection to the next non-disabled item (wraps around).
isSelected
Returns true if the item with the given internal ID is currently selected.
selectedClass
CSS class applied to selected items, sourced from the group props.
items
Ordered list of all registered group items.
getItemIndex
Finds the internal index of an item by its external value.

Usage

Examples

Ready-to-paste usage snippets.

Defining a group provider component

vue

Registering a child item

vue