BbCheckboxGroup

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.

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.

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; 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.

Disables the component.

Locks every option, ticked ones 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.

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.

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 whole fieldset, which is the concrete payoff over a hand-stacked row of BbCheckbox, where the message has to be pinned to one arbitrary box.

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.

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.

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.

Only additional row fields: today one, description, the muted line under each option. Nothing is read implicitly: an item carrying a description field shows nothing until you map it here.

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.

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

A property path ("fullName", "profile.city") or a function. Omit it for primitive items, where the value is its own label, and for objects with a label (or text) key, which is read by default.

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.

Prefer a stable primitive id. With this unset the model holds the item's own value key when it has one, otherwise the whole item, which works (matching is structural, not by reference), but an id survives a refetch and is readable in a payload.

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' }).

Splits the legend from the options, not the options from each other; that is list-layout. Defaults to vertical, which is why the legend sits above.

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. inside draws the fieldset border and sets the legend on it.

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.

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).

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

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 is an array: unbound, it starts empty, and a non-array value such as null 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.

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, indicator, item, itemDescription, label, legend, list, message, root. States: checked, disabled, errors, focused, focusVisible, hasValue, line, loading, pill, readonly, warnings.

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.

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.

Validates the array as a single field, so required means "at least one". Only inside a BbForm; outside one, compute errors yourself.

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.

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.

A tab-strip look (Q76.11 d): 'pill' (a pill per run of adjacent picks) or 'line' (a bar under each pick). list-layout="vertical" stacks it. Register more with checkboxVariants. Unset: the group's own rows.

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 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.

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 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, description }. 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 when the required marker shows.

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

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