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.
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.
- propsrequiredIGroupProps
- Props of the parent group component: modelValue, multiple, mandatory, max, selectedClass, disabled.
- injectKeyrequiredInjectionKey<IGroupProvide>
- Unique injection key used to link the group provider with its children. Must be the same symbol in both useGroup and useGroupItem calls.
- requiredbooleantrue
- 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
Registering a child item