BbSwitchGroup

Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.

Compact density. Swaps --bb-label-spacing-y for --bb-label-spacing-y-compact, so tune a compact group's label gap with the -compact token, not the base one.

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

Timeout used to debounce response to changes to dependencies.

Text between the label and the input. Unlike the hint it is always visible; it joins the input's 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.

Disables the component.

Locks every switch, the ones that are on included, and keeps the values out of a native post. To freeze a selection that must still be submitted, use readonly.

String displayed when there are no items to display.

After every applied, successful load (an empty one included), drops the model values the options no longer contain (a single value resets to null). A failed load never prunes.

Error messages under the field, a string or array, in an aria-live="polite" region and first in the control's aria-describedby, so they are re-read when it regains focus.

One channel for the fieldset, and it paints every row. On an instant-save group a refused write concerns one row, so report it in a status line or a toast instead.

String displayed in the empty state while the latest load FAILED (the items provider threw): the twin of emptyText for that case.

Keep this control out of the enclosing BbForm entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch).

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.

Prefix for the ids of each option's input and of the label, description and message. Generated when omitted.

Vertical position of the control in a side-by-side row; not inputPosition, the horizontal one. Omitted, the control's first line meets the label's.

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

Vertical position of each option's control in its row; 'center' is the middle of the label plus its description. Omitted, it sits on the label's first line.

Vertical position of each option's label in its row. Omitted, it stays as it is.

How each row's input and label sit together, in the layout keywords: 'auto', 'vertical', 'horizontal', 'label-fill', 'input-fill', or a two-word ratio pattern like 'xx xxxxx'.

ADDITIONAL row fields, never the text or value: description, a muted line under the label (it may wrap; announced as the option's description). An object of paths or getters, or a function of the item; nothing is read implicitly.

Swaps each row's input and label from their natural order (input first), in every item-layout. reverse swaps the legend and the options instead.

The options: an array, or a provider called with a BbCheckboxGroupItemsContext (BbSwitchGroupItemsContext on a switch group) (reason, modelValue, signal), sync or async. A provider fails by THROWING, never by returning []: the rows clear and #empty gets the error.

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. Unset: own label, else text ({ label, value } needs no accessor).

Defines a path that returns a property of the object to use as value or a function that returns any value. Unset: own value, even null.

Vertical position of the label block in a side-by-side row; not labelPosition, the horizontal one. Omitted, the label's first line meets the control's.

How label and input sit together: 'vertical', 'horizontal' (50/50), 'auto', 'label-fill', 'input-fill', a ratio like 'xx xxxxx', or a per-breakpoint map ({ default: 'vertical', md: 'xx xxxxx' }).

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.

How the rows sit in the list: 'horizontal' (on a line, wrapping), 'vertical' (stacked), 'vertical-stretch' (stacked, as wide as the list) or 'tiles' (equal boxes; --tile-min-width on pt:list sets the narrowest).

A settings list is vertical-stretch with item-layout="label-fill" and item-reverse: every row full width, the switch on the trailing edge.

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.

True by default, so the model is an array: unbound, it starts empty, and a non-array value such as null throws on mount. 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.

Keeps the hint displayed.

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

Passthrough, attribute form: one attribute per part, pt:<part>, and per part and state, pt:<part>:<state>. Parts: description, hint, icon, item, itemDescription, label, legend, list, message, root. States: checked, disabled, errors, focused, focusVisible, hasValue, loading, readonly, warnings.

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.

vee-validate rules for this field. Only inside a BbForm.

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: the predicate locks the items it rejects and max caps the rest. Where v2's per-item disabled field went: that field is inert in v3, silently, so locked feature flags become flippable.

The field's name in validation messages ({field}): "Email is not valid". Defaults to the label (or legend), then "This field"; never the name. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). BbForm only.

When the field validates: aggressive (each change), balanced (on leave, then live while in error), lazy (on leave), submit-only, submit-live. Unset: the BbForm's validation-mode, then formControls.validationMode ('balanced'). BbForm only.

Warning messages under the field, a string or array: amber, in their own aria-live region and in the control's aria-describedby after the errors. Non-empty turns on the warning state; errors win when both are set.

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 switch inputs loses focus. Forwards the original DOM FocusEvent.

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

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

Emitted when one of the generated switch 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 switch inputs. Forwards the original DOM Event.

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

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

Emitted when a pointing device button is released over a switch 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.

Content shown when no options are available (replaces the default "no data" text). error is what the latest failed load rejected with, untouched, and null when nothing failed — a failed load clears the rows, so this slot is where it shows.

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 rendered before the first option, inside the options container.