createGroup API

Multi-selection with tri-state (mixed/indeterminate) support for checkbox trees, grouped toggles, and any pattern where items can be partially selected.

Explore these related pages for additional context and usage patterns.

Page	Category
createGroup	Selection
createSelection	Selection
Group	Providers
Checkbox	Forms

Creates a new group instance with batch selection and tri-state support. Extends createSelection to support selecting, unselecting, and toggling multiple items at once by passing an array of IDs. Adds tri-state (mixed/indeterminate) support for checkbox trees and similar use cases.

createGroupContext

(_options?: GroupContextOptions) => ContextTrinity<R>

Creates a new group context.

useGroup

(namespace?: string) => R

Returns the current group instance.

Options

events

boolean | undefined

Enable event emission for registry operations

Default: false

reactive

boolean | undefined

Enable reactive behavior for registry operations

Default: false

disabled

MaybeRefOrGetter<boolean> | undefined

Disabled state for the entire model instance

Default: false

enroll

MaybeRefOrGetter<boolean> | undefined

Auto-select tickets on registration

Default: true

multiple

MaybeRefOrGetter<boolean> | undefined

Allow multiple tickets to be selected simultaneously

Default: false

mandatory

MaybeRefOrGetter<boolean | "force"> | undefined

Controls mandatory selection behavior: - false (default): No mandatory selection enforcement - true: Prevents deselecting the last selected item - 'force': Automatically selects the first non-disabled item on registration

Properties

collection

ReadonlyMap<ID, E>

The collection of tickets in the registry

size

number

The number of tickets in the registry

selectedIds

Reactive<Set<ID>>

Set of currently selected ticket IDs

selectedItems

ComputedRef<Set<E>>

Computed Set of selected ticket instances

selectedValues

ComputedRef<Set<E["value"] extends Ref<infer U, infer U> ? U : E["value"]>>

Computed Set of selected ticket values

disabled

MaybeRefOrGetter<boolean>

Disabled state for the entire model instance

multiple

MaybeRefOrGetter<boolean>

Whether the selection allows multiple selections

selectedIndexes

ComputedRef<Set<number>>

mixedIds

Reactive<Set<ID>>

Set of mixed/indeterminate ticket IDs

mixedItems

ComputedRef<Set<E>>

Set of mixed/indeterminate ticket instances

isNoneSelected

Readonly<Ref<boolean, boolean>>

Whether no items are currently selected

isAllSelected

ComputedRef<boolean>

Whether all selectable (non-disabled) items are selected

isMixed

ComputedRef<boolean>

Whether some but not all selectable items are selected

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => readonly ID[]

Get all registered IDs

browse

(value: E["value"]) => readonly ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

Lookup a ticket by index number

get

(id: ID) => E | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>, event?: string) => E

Update or insert a ticket by ID

values

() => readonly E[]

Get all values of registered tickets

entries

() => readonly [ID, E][]

Get all entries of registered tickets

unregister

(id: ID) => void

Unregister a ticket by ID

reindex

() => void

Reset the index directory and update all tickets

move

(id: ID, toIndex: number) => E | undefined

Move a ticket to a new index position

reorder

(ids: ID[]) => void

Reorder the registry to match a canonical permutation of ids in one pass.

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => E | undefined

Seek for a ticket based on direction and optional predicate

on

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Listen for registry events

off

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Stop listening for registry events

emit

<K extends Extensible<RegistryEventName>>(event: K, data: EventPayload<E, K>) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

offboard

(ids: ID[]) => Partial<Z>[]

Offboard multiple tickets at once, returning the input shapes that were removed.

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring cache invalidation and event emission until complete

reset

() => void

Reset selection state without destroying the registry

selected

(id: ID) => boolean

Check if a ticket is currently selected

apply

(values: unknown[], options?: { multiple?) => void

Apply external values to the model

mandate

() => void

Mandate selected ID based on "mandatory" option

select

(ids: ID | ID[]) => void

Select one or more Tickets by ID

unselect

(ids: ID | ID[]) => void

Unselect one or more Tickets by ID

toggle

(ids: ID | ID[]) => void

Toggle one or more Tickets ON and OFF by ID

mix

(ids: ID | ID[]) => void

Set one or more Tickets to mixed/indeterminate state by ID

unmix

(ids: ID | ID[]) => void

Clear mixed/indeterminate state from one or more Tickets by ID

mixed

(id: ID) => boolean

Check if a ticket is in mixed/indeterminate state by ID

selectAll

() => void

Select all selectable (non-disabled) items

unselectAll

() => void

Unselect all items (respects mandatory option)

toggleAll

() => void

Toggle between all selected and none selected

register

(ticket?: Partial<Z>) => E

onboard

(registrations: Partial<Z>[]) => E[]

Onboard multiple tickets at once