Checkbox

Form & Input
stable

Form checkbox with label, hint, validation messages, indeterminate state, and full keyboard/accessibility support. Wraps OrigamInput and OrigamCheckboxBtn.

Structure

Anatomy

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

Anatomy of OrigamCheckboxSchematic of the Checkbox component with 5 numbered internal parts. Checkbox label Hint / validation messages 1 2 3 4 5 Checkbox wraps OrigamInput (frame) + OrigamCheckboxBtn (control)
Anatomy of <origam-checkbox> — 5 internal parts.
1.origam-checkbox
Root element extending OrigamInput. Holds the label, hint and messages frame.
2.origam-checkbox-btn
Visual checkbox control (OrigamCheckboxBtn). Contains the box and icon.
3.origam-selection-control__label
Text label. Bound via htmlFor to the hidden native .
4.origam-input__details
Messages/hint area. Hidden when hideDetails=true.
5.origam-selection-control__input
Hidden native that carries the value for form submissions.

API

Props

All props accepted by this component, with their type, default value and description.

id
string
HTML id attribute. Auto-generated as "checkbox-{uid}" when omitted.
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
centerAffix
boolean
hideDetails
boolean | string
false
Hides the messages/hint area. 'auto' hides when there are no messages.
hideSpinButtons
boolean
hint
string
Helper text displayed below the checkbox.
persistentHint
boolean
false
Always shows the hint even when the checkbox is not focused.
messages
Array<string> | string
Validation or informational messages displayed below the checkbox.
density
'default'
Adjusts the vertical padding density of the input frame.
padding
boolean | number | string
Padding applied to the checkbox root element.
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
margin
boolean | number | string
Margin applied to the checkbox root element.
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
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
color
Intent or custom color applied to the checked state background and border.
bgColor
TColor
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
false
Applies a border to the input frame.
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
elevation
TElevation
height
number | string
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
direction
TDirection
disabled
boolean
false
Disables the checkbox. Sets aria-disabled and prevents interaction.
error
string | boolean
false
Puts the checkbox in an error state (red border and icon).
errorMessages
Array<string> | string
Error messages displayed below the checkbox when in error state.
maxErrors
number | string
name
string
readonly
boolean
false
Makes the checkbox non-interactive without visually disabling it.
rules
Array<any>
modelValue
any
Bound value of the checkbox. Use with v-model. Accepts boolean, array or any trueValue/falseValue.
validateOn
TValidateOn
validationValue
any
focused
boolean
appendAvatar
string
appendIcon
TIcon
prependAvatar
string
prependIcon
TIcon
prependAriaLabel
string
appendAriaLabel
string
size
TSize | number
fontSize
TFontSize
fontWeight
TFontWeight
lineHeight
TLineHeight
indeterminate
boolean
false
Puts the checkbox in an indeterminate (neither checked nor unchecked) state. Typically used for "select all" parent checkboxes.
indeterminateIcon
Icon rendered inside the checkbox when in indeterminate state.
label
string
Text label rendered next to the checkbox.
trueValue
any
true
Value used for the checked state. Defaults to boolean true.
falseValue
any
false
Value used for the unchecked state. Defaults to boolean false.
value
any
Value used when this checkbox is part of an array-bound group (v-model is an array).
required
boolean
type
string
valueComparator
(a: any, b: any) => boolean
falseIcon
TIcon
trueIcon
TIcon
multiple
boolean
inline
boolean
hover
boolean | IStateEffectConfig
hoverClass
string
ripple
boolean | { class: string }
active
boolean | IStateEffectConfig
activeClass
string

API

Slots

Content slots exposed by this component.

#default
Replaces the entire CheckboxBtn (advanced). Receives the computed input state for wiring ARIA.
#label
Custom label content. Replaces the text label rendered next to the checkbox.
#input
Replaces the visual checkbox control (the styled box and icon). Useful for a completely custom indicator.

API

Emits

Events emitted by this component.

@update:modelValue
any
Fired when the checked state changes. Carries the new value (trueValue or falseValue).
@update:focused
any
Fired when the checkbox gains or loses focus.
@update:indeterminate
boolean
Fired when the indeterminate state is cleared by user interaction.
@click:label
MouseEvent
Fired when the user clicks the label text.

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 OrigamInput or OrigamCheckboxBtn.
Ref<string>
Reactive CSS string generated by useStyle.
ComputedRef<string>
Resolved id string (prop or auto-generated).
() => void
Injects the computed style sheet.
() => void
Removes the injected style sheet.
Ref<boolean>
True once the style sheet has been injected.
string
Unique style-sheet ID for scoping injected CSS.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

Minimum height of the checkbox input row, before density is applied.
Background of the checkbox visual box in unchecked state.
Background of the checkbox box when checked.
Border color of the checkbox box in unchecked state.
Border color when checked.
Border radius of the checkbox box.
Color of the check mark icon inside the box.
Label text color.

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 <input type="checkbox"> behaviour.
TabMoves focus to the next interactive element.

Notes

  • The hidden native <input type="checkbox"> carries aria-checked (including "mixed" for indeterminate). Screen readers announce state correctly.
  • aria-describedby links the checkbox to the messages container (messagesId) so validation errors are announced.
  • When disabled=true, the native input is disabled and pointer events are removed. Screen readers announce "dimmed" state.

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

With validation

vue

Ecosystem

Family

Components from the same folder that share conventions and often compose together.