CheckboxBtn

Form & Input
stable

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…

unchecked

Rendering the live preview…

checked

Rendering the live preview…

indeterminate

Rendering the live preview…

disabled

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamCheckboxBtnSchematic of the CheckboxBtn component — delegates to origam-selection-control. origam-checkbox-btn ① origam-selection-control ② icon ③ label / #label ④ Delegates all selection logic to OrigamSelectionControl (trueIcon / falseIcon / indeterminateIcon)
Anatomy of <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.

indeterminate
boolean
false
When true the indeterminateIcon is shown and aria-checked="mixed" is set. Automatically cleared on the first change.
indeterminateIcon
MDI_ICONS.MINUS_BOX
Icon rendered when indeterminate=true. Overrides both trueIcon and falseIcon.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
label
string
Text label rendered adjacent to the checkbox icon.
trueValue
any
true
Value emitted when the checkbox is checked. Useful for v-model with non-boolean arrays.
falseValue
any
false
Value emitted when the checkbox is unchecked.
value
any
Item value when used inside a selection group (e.g. BtnToggle). Checked state is determined by group membership.
required
boolean
false
Sets the native required attribute on the underlying input.
disabled
boolean
false
Disables the checkbox. Sets aria-disabled and prevents interaction.
error
string | boolean
name
string
readonly
boolean
type
string
modelValue
any
Bound checked state. Supports v-model binding with booleans, arrays or custom true/false values.
valueComparator
(a: any, b: any) => boolean
falseIcon
TIcon
trueIcon
TIcon
multiple
boolean
inline
boolean
color
Foreground colour of the checked icon and label text.
bgColor
Background colour override for the control surface.
hover
boolean | IStateEffectConfig
hoverClass
string
density
DENSITY.DEFAULT
Adjusts vertical padding density of the control.
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
rounded
boolean | number | string | TRounded | null | undefined
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
elevation
TElevation
ripple
boolean | { 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:indeterminate
any
Fired when indeterminate is cleared (always false). Cleared on first change.
@update:modelValue
any
Fired when the checked state changes. Emits the new value (boolean, array item, or trueValue/falseValue).
@click:label
MouseEvent
Fired when the user clicks the label area (not the icon).
@update:focused
boolean
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

checkbox

Keyboard interactions

Keyboard interactions
KeyAction
SpaceToggles the checked state (native checkbox behaviour).
TabMoves 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

vue

Indeterminate state

vue

Array v-model (multi-select)

vue