BbCheckboxGroup

Sets autofocus on page load.

Displays the component in a compact version.

Defines an array of dependencies that will trigger actions in the component upon change.

Only meaningful when items is a provider function: it names what makes the group call it again. A dependency that is a text field wants deps-debounce-time with it; one that is another group does not.

Timeout used to debounce response to changes to dependencies.

Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via aria-describedby (after any errors / warnings, before the hint).

One description for the whole set — there is no per-option equivalent. When each option needs its own line, the options are not uniform and a BbCheckbox per row is the honest answer.

Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like xx xxxxx.

Splits the legend from the options, not the options from each other — that is input-direction. Defaults to vertical, which is why the legend sits above.

Disables the component.

Currently exempts options that are already ticked, so a disabled group with a selection can still be unticked. Until that is fixed in the library, lock a group carrying a selection with readonly.

If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence.

Drops model entries the current options no longer contain. Worth it when the options depend on another field, and not otherwise — a selection can vanish without the user doing anything.

Can be a string or an array of string containing the messages to display. They render in an aria-live="polite" region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's aria-describedby, so the reason the field is invalid is re-read whenever the control regains focus.

One channel for the whole fieldset, which is the concrete payoff over a hand-stacked row of BbCheckbox — there, the message has to be pinned to one arbitrary box.

Define if the component should be in an error state. It usually attaches a CSS class for styling purposes.

Define if the component should be in a warning state. Same chrome as errors with --bb-warn; errors take priority.

Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use hideLegend for that.

Hides each option's text, not the legend. For a group whose options are drawn entirely by the icon slot, and nothing else.

Visually hides the legend of the fieldset while maintaining accessibility.

Hides the group's name while keeping it for assistive technology. For when a visible heading right above already says the same words — never as a way to avoid writing one.

Text box to be displayed near the input, usually to indicate instructions.

The identifier of the component.

Defines the direction of the inputs in the fieldset.

Lays the options out inside the fieldset. Defaults to horizontal: a wrapping row, not a stack.

Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.

ADDITIONAL row fields resolved from each item — never its text or value (those stay on itemText / itemValue). Option groups accept one field: - description — a muted line under the option label, beside the control; it may wrap. Either an object with a path or getter per field ({ description: 'email' }) or a function returning the fields ((item) => ({ description: item.email })). Without it no field renders — an item's own description is never read implicitly — and an empty value renders nothing for that item. The description is announced as the option's description, never part of its name. To disable individual options use selectable.

Used to retrieve items; can be an array or a function.

An array, or a function called on mount and after every dependencies change, returning an array or a promise. Options whose resolved value duplicates an earlier one are dropped silently, first occurrence winning.

Defines a path that returns a property of the object to use as text or a function that returns a string.

A property path ("fullName", "profile.city") or a function. Omit it for primitive items, where the value is its own label.

Defines a path that returns a property of the object to use as value or a function that returns any value.

Prefer a stable primitive id. With this unset the model holds the whole item, which works — matching is structural, not by reference — but an id survives a refetch and is readable in a payload.

Text content of the legend.

Required, because it is the fieldset's accessible name: a screen reader announces it on entry, so every box is heard as an answer to a named question. Hide it with hide-legend when a visible heading already carries it.

Legend rendering mode. 'outside' renders the legend above the fieldset in the normal flow; 'inside' overlays the legend inside the fieldset border. Floating mode is not supported for option groups (checkbox, radio or switch) — there is no single field for the legend to float against.

No floating mode here — a group has no single input for a label to float into.

Sets the text alignment of the label.

Renamed from v2's labelPosition, with no change in behaviour. The rename is silent: an unknown attribute falls through to the DOM, so the alignment just stops applying.

String displayed while items are being loaded.

Worth setting to something specific. "Loading hubs…" tells the reader more than the default.

Maximum number of selected items.

A shape rule, not a validation rule: it prevents the extra choice rather than complaining about it. Once the cap is reached the options that are off render disabled and the ticked ones stay live, so the user swaps rather than getting stuck.

Used by v-model. Can be an array of any serializable type.

Timeout used to debounce response to changes to modelValue.

Enables multi-selection behavior. When true, modelValue must be an array. When false, modelValue should be a single value.

True by default, so the model must be an array — a non-array throws on mount. Setting it false gives a single-value control that emits a bare value and null; it works, and an exclusive choice drawn as checkboxes is BbRadioGroup.

Defines the name of the input.

String displayed when there are no items to display.

Keeps the hint displayed.

Passthrough, object form: the same keys as the pt:* attributes without the prefix. See the pt:<part> row.

Sets the input in a readonly state.

Keeps every box focusable and submitted while swallowing every change. The right lock for a value the user may read and must not alter, and the reliable one when the group already carries a selection.

Reverses the layout. Applicable in every direction the order of the label and the input is swapped.

Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled.

A boolean for the group or a predicate over the item. This is where v2's per-item disabled field went: that field is inert in v3, silently, so options that used to render locked become tickable.

Warning messages to display beneath the field, in their own aria-live region and amber (--bb-text-warn). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's aria-describedby, after any errors and before the description/hint.

The array of resolved values, re-emitted in full on every change — never the option that moved. Diff it against the previous value when you need to know what changed.

Emitted when the group becomes active (focus/click enters it).

Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM FocusEvent.

Emitted when an option is toggled. Forwards the original DOM Event from the checkbox input.

Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM MouseEvent.

Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM FocusEvent.

Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.

Emitted on native input events from generated checkbox inputs. Forwards the original DOM Event.

Emitted for keyboard interaction on generated checkbox inputs. Forwards the original DOM KeyboardEvent.

Emitted when a pointing device button is pressed over a checkbox input. Forwards the original DOM MouseEvent.

Emitted when a pointing device button is released over a checkbox input. Forwards the original DOM MouseEvent.

Emitted with the coherent next selection array whenever selection changes.

Content rendered after the last option, inside the options container.

Replaces the description text. Provided alone (no description prop) it still renders the description region and wires it into aria-describedby.

Replaces the default checkmark icon for each checkbox option.

Replaces the box visual per option, and receives item and text alongside the live state.

Replaces the default label text for each option.

One template for every option, scoped { item, text, checked }. Decorate text rather than dropping it — what renders here is the option's accessible name. This is what replaced v2's removed #option:prepend and #option:append.

Replaces the default fieldset legend text for the group.

Scoped { text, hasErrors, hasWarnings }, plus showAsterisk on the validated import.

Content shown while options are loading (replaces the default loading text).

Content shown when no options are available (replaces the default "no data" text).

Content rendered before the first option, inside the options container.