Checkbox
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.
<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.
- idstring
- HTML id attribute. Auto-generated as "checkbox-{uid}" when omitted.
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- centerAffixboolean
- hideDetailsboolean | stringfalse
- Hides the messages/hint area. 'auto' hides when there are no messages.
- hideSpinButtonsboolean
- hintstring
- Helper text displayed below the checkbox.
- persistentHintbooleanfalse
- Always shows the hint even when the checkbox is not focused.
- messagesArray<string> | string
- Validation or informational messages displayed below the checkbox.
- Adjusts the vertical padding density of the input frame.
- paddingboolean | number | string
- Padding applied to the checkbox root element.
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- Margin applied to the checkbox root element.
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- Border-radius override.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- color
- Intent or custom color applied to the checked state background and border.
- bgColorTColor
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border to the input frame.
- 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
- elevationTElevation
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- directionTDirection
- disabledbooleanfalse
- Disables the checkbox. Sets aria-disabled and prevents interaction.
- errorstring | booleanfalse
- Puts the checkbox in an error state (red border and icon).
- errorMessagesArray<string> | string
- Error messages displayed below the checkbox when in error state.
- maxErrorsnumber | string
- namestring
- readonlybooleanfalse
- Makes the checkbox non-interactive without visually disabling it.
- rulesArray<any>
- modelValueany
- Bound value of the checkbox. Use with v-model. Accepts boolean, array or any trueValue/falseValue.
- validateOnTValidateOn
- validationValueany
- focusedboolean
- appendAvatarstring
- appendIconTIcon
- prependAvatarstring
- prependIconTIcon
- prependAriaLabelstring
- appendAriaLabelstring
- sizeTSize | number
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- indeterminatebooleanfalse
- 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.
- labelstring
- Text label rendered next to the checkbox.
- trueValueanytrue
- Value used for the checked state. Defaults to boolean true.
- falseValueanyfalse
- Value used for the unchecked state. Defaults to boolean false.
- valueany
- Value used when this checkbox is part of an array-bound group (v-model is an array).
- requiredboolean
- typestring
- valueComparator(a: any, b: any) => boolean
- falseIconTIcon
- trueIconTIcon
- multipleboolean
- inlineboolean
- hoverboolean | IStateEffectConfig
- hoverClassstring
- rippleboolean | { class: string }
- activeboolean | IStateEffectConfig
- activeClassstring
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:modelValueany
- Fired when the checked state changes. Carries the new value (trueValue or falseValue).
- @update:focusedany
- Fired when the checkbox gains or loses focus.
- @update:indeterminateboolean
- Fired when the indeterminate state is cleared by user interaction.
- @click:labelMouseEvent
- 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
Keyboard interactions
| Key | Action |
|---|---|
| Space | Toggles the checked state. Native <input type="checkbox"> behaviour. |
| Tab | Moves 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
Indeterminate state
With validation
Ecosystem
Family
Components from the same folder that share conventions and often compose together.