BbSwitchGroup

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.

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. It is also the only place max and selectable get explained — a switch that refuses to move with no reason on screen reads as broken.

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

Disables the component.

Currently exempts options that are already on, so a disabled group can still be switched off. Use readonly to lock a group that carries a selection.

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.

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 fieldset. On an instant-save group it is where a refused write explains itself — pair it with a toast, since the group may be off screen by then.

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.

Visually hides the legend of the fieldset while maintaining accessibility.

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.

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.

Same mapping as BbCheckboxGroup, down to the accessors and the silent de-duplication by resolved value.

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

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

Text content of the legend.

Required. It names the set of states, which is what a screen reader announces before the first switch.

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.

Sets the text alignment of the label.

String displayed while items are being loaded.

Maximum number of selected items.

Once the cap is reached the switches that are off render disabled and the ones that are on 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.

v2 advertised this prop and never forwarded it: a group set to single-select still emitted an array. v3 honours it, so a model written expecting an array now receives a bare value or null, with no warning.

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 the switches focusable and submitted while swallowing changes — which is what an instant-save group holds itself in while its request is in flight.

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, resolving through the same per-option path as max. Where v2's per-item disabled field went: that field is inert in v3, silently, so locked feature flags become flippable.

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 the options that are on, re-emitted in full on every change. An instant-save handler receives the whole next array and diffs it against the previous one; reading the single toggle off a @change event is how the two drift apart.

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.

Bind this together with :model-value instead of using v-model whenever a failed write has to put the previous value back.

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 switch track visual for each option. Receives the switch state plus the source item and its display text.

Replaces the entire track and thumb per option, not a glyph inside them, so the slot content has to communicate on, off and focused by itself. The input underneath keeps role="switch" either way.

Replaces the default label text for each option.

Replaces the default fieldset legend text for the group.

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.