Checkbox

Form & Input
stable

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

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

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

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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

Emplacements de contenu exposés par ce composant.

#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

Événements émis par ce composant.

@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

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

<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.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

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

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Rôles ARIA

checkbox

Interactions clavier

Interactions clavier
ToucheAction
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.

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Basic checkbox

vue

Indeterminate state

vue

With validation

vue

Écosystème

Famille

Composants du même dossier qui partagent les conventions et se composent souvent ensemble.