Skip to content

OrigamCheckboxGroup ​

The checkbox counterpart of [OrigamRadioGroup] — a labelled, validated group of checkboxes bound to a single v-model.

vue
<origam-checkbox-group
    v-model="selected"
    label="Notifications"
    :items="[
        { label: 'Email', value: 'email' },
        { label: 'SMS', value: 'sms' },
        { label: 'Push', value: 'push' }
    ]"
/>

The one difference with OrigamRadioGroup ​

OrigamRadioGroup Omits multiple from its props and hardcodes :multiple="false" — correct, because radio semantics are exactly one of.

A checkbox group is the opposite: selecting several is the normal case. multiple is therefore exposed here and defaults to true.

Setting multiple={false} stays legitimate — it yields a group of checkboxes behaving as an exclusive choice, which some designs use for a "none of the above" toggle list. Nothing forbids it; it is simply not the default.

Everything else — the <OrigamInput> chrome, label, validation messages, items, the #default / #label / #item slots, the visual cascade — mirrors OrigamRadioGroup deliberately, so the two are learned once.

Props ​

PropTypeDefaultDescription
modelValueunknown[]—Selected values. An array, since several may be selected.
multiplebooleantrueAllow more than one selection. This is the difference with RadioGroup.
itemsICheckboxProps[][]The checkboxes to render. Each entry is spread onto its <OrigamCheckbox>.
labelstring—Group label, rendered through <OrigamLabel> (as a span) and wired as aria-labelledby via a dedicated label wrapper.
requiredboolean—Forwarded to the label.

The group also accepts the full IInputProps surface (validation, messages, density, readonly, disabled…), plus padding / margin / border / rounded / elevation.

Slots ​

SlotScopeDescription
default{ id, messagesId, isDisabled, isReadonly, isValid }Replaces the whole group body.
label{ label, required }Replaces the rendered label.
item{ id, messagesId, isDisabled, isReadonly, isValid }Replaces each rendered checkbox.

⚠️ #item receives the outer <OrigamInput> scope, not the individual item being rendered. That is inherited from OrigamRadioGroup and kept identical on purpose — documented here so the asymmetry with the slot's name is not mistaken for a bug.

Emits ​

EventPayloadDescription
update:modelValueunknown[]Fired on every selection change.

⛔ Declared from the start, deliberately. OrigamRadioGroup shipped with no emits option at all while binding useVModel(props, 'modelValue') as v-model on three children. Vue stays silent in that case — its warning only fires when a component has an emits option that omits the event, never when it has none. The symptom was onUpdate:modelValue stuck in $attrs and re-applied onto <origam-input> by the rootAttrs spread: the consumer's handler ran twice per selection.

Visual cascade ​

Group-level color, bgColor, density and size reach the checkboxes through an <OrigamDefaultsProvider> wrapper — not by reading a v-for ref. Reading such a ref (reassigned on every render) inside a computed re-triggered rendering endlessly on OrigamRadioGroup ("Maximum recursive updates in OrigamInput").

Only props the consumer actually passed are forwarded (see #263). This matters more than it looks: color / bgColor are TColor, which includes false, so Vue's boolean-prop coercion resolves each unset prop to the concrete value false — there is no undefined left for a naive filter to catch. Forwarded unconditionally, they win the mergeDeep against a theme's 'origam-checkbox' entry and erase it silently.

Group naming ​

aria-labelledby points at a dedicated label wrapper ({id}-label, display: contents) — not at the <OrigamLabel> element, and not at the control group itself. It is emitted when label is set or the #label slot is filled, so overriding the slot keeps the group named. With neither, no aria-labelledby is emitted at all — this DS never fabricates a fallback name (#622).

#814

Until 2.17.x the same id was carried by both the <OrigamLabel> and the control group. Measured in Chromium: aria-labelledby resolved to whichever came first in document order — the label — so the default rendering was already named correctly (group "Notifications"). But with label set and the #label slot overridden, the label element was gone and the only remaining carrier was the group itself, so the group named itself with its own options. With the slot overridden and no label prop, the group had no accessible name at all.

Example — exclusive mode ​

vue
<origam-checkbox-group
    v-model="answer"
    :multiple="false"
    label="Pick one"
    :items="options"
/>