Skip to content

OrigamCheckboxBtn ​

The bare checkbox control — the check itself, without the <OrigamInput> chrome (label block, validation messages, details).

vue
<origam-checkbox-btn
    v-model="accepted"
    label="I agree"
/>

When to use which ​

ComponentUse it when
OrigamCheckboxBtnYou want only the control — inside a table cell, a list row, a toolbar, or any layout that already owns its labelling and error display.
OrigamCheckboxYou want the full form field: label block, validation messages, details, focus state. It wraps this component.
OrigamCheckboxGroupYou want several checkboxes bound to one v-model, with a group label and shared validation.

Props ​

PropTypeDefaultDescription
modelValueany—Bound value. An array turns on accumulation (see below).
valueany—The value written to the model when checked. Falls back to trueValue, then true.
trueValueany—Explicit checked value. Wins over value.
falseValueanyfalseValue written when unchecked (single mode only).
multiplebooleanautoAccumulate into an array. Leave it unset unless you mean it — see the warning below.
labelstring—Inline label rendered next to the control.
indeterminatebooleanfalseRenders the mixed state and sets aria-checked="mixed". Cleared on the next user change.
indeterminateIconTIcon—Icon for the mixed state.
trueIcon / falseIconTIcon—Icons for checked / unchecked.
valueComparator(a, b) => boolean—How values are matched inside an array model. Supply it for object values.
disabled · readonly · required · error · name · inlineStandard control surface.

⛔ Do not pass multiple "just to be explicit". Vue's boolean-prop coercion resolves an unset boolean prop to the concrete value false, never to null. OrigamSelectionControl auto-detects array mode with props.multiple == null && Array.isArray(model) — so forwarding a false you did not mean switches accumulation off and every click overwrites the previous one, silently. That is exactly how the data-loss bug of #396 travelled down the chain.

Emits ​

EventPayloadDescription
update:modelValueanyFired on toggle. Carries the array in accumulation mode.
update:indeterminatebooleanFired when the mixed state is cleared by a user change.
click:labelMouseEventThe label element was clicked.

⛔ update:focused is NOT emitted, and is no longer declared. This component has no focus handling at all — no focus/blur handler, no useFocus call — and focused is not even one of its props. The event was declared through IFocusEmits and could never fire: a dead API surface, removed under the inspection grid's C5 criterion.

Use OrigamCheckbox if you need it — it calls useFocus(props), whose useVModel(props, 'focused') emits update:focused for real.

Slots ​

SlotScopeDescription
default{ model, color, bgColor, icon, props }Replaces the rendered control entirely.
label—Replaces the inline label.
input{ props, icon, textColorStyles, backgroundColorStyles, model }Replaces the <input> and its icon.

Accumulation ​

An array modelValue accumulates:

vue
<origam-checkbox-btn v-model="selected" value="a" label="A" />
<origam-checkbox-btn v-model="selected" value="b" label="B" />
<!-- selected === ['a', 'b'] once both are checked -->

Checking adds the control's value, unchecking removes it. Both controls must share the same v-model — the accumulation is computed from the current model, not from a local flag.

Theming — le canal passe par selection-control ​

⛔ Il n'existe AUCUN token --origam-checkbox---* ni --origam-checkbox-btn---*, et c'est voulu. OrigamCheckboxBtn ne peint rien lui-meme : il delegue tout le rendu a <OrigamSelectionControl>, dont la SCSS est la seule a lire des variables. Habiller une case a cocher, c'est donc agir sur --origam-selection-control* — la surface, le halo, l'icone et le label y sont tous adressables :

css
:root {
    --origam-selection-control__input---border-radius: 4px;
    --origam-selection-control__input---overlay-background-color: currentColor;
    --origam-selection-control__icon---opacity: 0.4;
    --origam-selection-control__label---color: var(--origam-color__text---secondary);
}

Les 46 tokens checkbox / checkbox-btn que l'ancien pipeline Style Dictionary declarait n'etaient lus par personne : ils sont partis avec packages/ds/tokens/ le 2026-08-31 (voir Design tokens dans le CLAUDE.md racine). Ne les recreez pas « pour la symetrie » : un token declare et jamais lu est un mensonge qui coute une session de debug a qui le trouve.

Pour un reglage par instance, la voie normale reste les props — color, density, rounded, elevation, trueIcon / falseIcon — puis, seulement si aucune prop ne couvre le besoin, un override de variable cible.

Accessibility ​

The rendered element is a real <input type="checkbox">, so the checked state, keyboard interaction and screen-reader semantics are the browser's, not a re-implementation. label for points at the input's id, disabled and name reach the control, and indeterminate produces aria-checked="mixed".