CheckboxBtn
Low-level checkbox control without the Input frame. Wraps OrigamSelectionControl to expose just the interactive icon and optional label, without hint or validation message wrappers.
Preview
Rendering the live preview…
uncheckedRendering the live preview…
checkedRendering the live preview…
indeterminateRendering the live preview…
disabledStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-checkbox-btn> — 4 internal parts. The root ① carries a single origam-selection-control ② child which renders the icon ③ and label ④.- 1.origam-checkbox-btn
- Root element. Hosts origam-selection-control and passes through computed classes and styles.
- 2origam-selection-control
- The underlying selection primitive. Manages model binding, focus, keyboard, ARIA and icon display.
- 3icon (via #input slot)
- Checkbox icon: falseIcon (unchecked) → trueIcon (checked) → indeterminateIcon (mixed). Swappable via the #input slot.
- 4label (via #label slot)
- Label text area. Replaces the label prop when the #label slot is used.
API
Props
All props accepted by this component, with their type, default value and description.
- indeterminatebooleanfalse
- When true the indeterminateIcon is shown and aria-checked="mixed" is set. Automatically cleared on the first change.
- Icon rendered when indeterminate=true. Overrides both trueIcon and falseIcon.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- labelstring
- Text label rendered adjacent to the checkbox icon.
- trueValueanytrue
- Value emitted when the checkbox is checked. Useful for v-model with non-boolean arrays.
- falseValueanyfalse
- Value emitted when the checkbox is unchecked.
- valueany
- Item value when used inside a selection group (e.g. BtnToggle). Checked state is determined by group membership.
- requiredbooleanfalse
- Sets the native required attribute on the underlying input.
- disabledbooleanfalse
- Disables the checkbox. Sets aria-disabled and prevents interaction.
- errorstring | boolean
- namestring
- readonlyboolean
- typestring
- modelValueany
- Bound checked state. Supports v-model binding with booleans, arrays or custom true/false values.
- valueComparator(a: any, b: any) => boolean
- falseIconTIcon
- trueIconTIcon
- multipleboolean
- inlineboolean
- color
- Foreground colour of the checked icon and label text.
- bgColor
- Background colour override for the control surface.
- hoverboolean | IStateEffectConfig
- hoverClassstring
- Adjusts vertical padding density of the control.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- rippleboolean | { class: string }
API
Slots
Content slots exposed by this component.
- #label
- Custom label content rendered in the selection control label zone.
- #input
- Replace the default checkbox icon / input element entirely. Receives model, current icon, and computed color style objects.
- #default
- Main label content. Overrides the label prop.
API
Emits
Events emitted by this component.
- @update:indeterminateany
- Fired when indeterminate is cleared (always false). Cleared on first change.
- @update:modelValueany
- Fired when the checked state changes. Emits the new value (boolean, array item, or trueValue/falseValue).
- @click:labelMouseEvent
- Fired when the user clicks the label area (not the icon).
- @update:focusedboolean
- Fired when focus state changes.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to a child component.
- Ref<string>
- Reactive CSS string generated by useStyle from the computed styles.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet into the document. Called automatically on mount.
- () => void
- Removes the injected style sheet. Called automatically on unmount.
- Ref<boolean>
- True once the style sheet has been injected into the DOM.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Border radius of the button-checkbox container.
- Default background colour.
- Background colour on hover.
- Background colour when checked.
- Default foreground text colour.
- Foreground colour when checked (on-primary surface).
- Default border colour.
- Border colour when checked.
- Label font size.
- Opacity when disabled.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Space | Toggles the checked state (native checkbox behaviour). |
| Tab | Moves focus to the next interactive element. |
Notes
- When indeterminate=true, aria-checked="mixed" is set on the underlying input element.
- Disabled state sets the native disabled attribute (the underlying input is a real <input type="checkbox">).
- Focus-visible outline is applied via CSS to the selection control. Controlled by OrigamSelectionControl.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic checkbox
Indeterminate state
Array v-model (multi-select)