Checkbox
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.
<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.
- 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
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: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
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
Interactions clavier
| Touche | 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.
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
Indeterminate state
With validation
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.