SelectionControl
Base selection-control primitive used by Checkbox, Radio, Switch and similar inputs. Renders a ripple zone, a native input and a label with full ARIA support.
Preview
Rendering the live preview…
uncheckedRendering the live preview…
checkedRendering the live preview…
radioRendering the live preview…
errorRendering the live preview…
disabledStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-selection-control> — 5 parts: root ①, wrapper ②, input zone ③ (with ripple), icon/native input ④, and label ⑤.- 1.origam-selection-control
- Root element. Flex-row, aligns wrapper and label. Carries state modifiers (dirty, disabled, error, focused, inline).
- 2.origam-selection-control__wrapper
- Square wrapper (40px + density). Hosts the ripple zone and the background color layer.
- 3.origam-selection-control__input
- Circular ripple zone (v-ripple). Contains the OrigamIcon (true/falseIcon) and the native input.
- 4input[type="checkbox|radio"] (native)
- Visually hidden native input. Manages browser check state, form submission, and screen-reader focus.
- 5.origam-selection-control__label
- Label container. Renders OrigamLabel with for/id wiring.
API
Props
All props accepted by this component, with their type, default value and description.
- labelstring
- Label text displayed next to the control via OrigamLabel.
- trueValueany
- Value emitted when the control is checked.
- falseValueany
- Value emitted when the control is unchecked.
- valueany
- Value for group context. Used by SelectionControlGroup to determine membership.
- requiredbooleanfalse
- Marks the control as required.
- disabledbooleanfalse
- Disables the control.
- errorstring | booleanfalse
- Puts the control in error state. Changes label and icon color.
- namestring
- Name attribute for the native input. Groups radio buttons for browser behaviour.
- readonlybooleanfalse
- Makes the control read-only (no interaction).
- typestring'checkbox'
- Native input type. Usually checkbox or radio. Determines ARIA semantics.
- modelValueany
- Current value. Bound with v-model. Compared against trueValue/falseValue (single) or array membership (group).
- valueComparator(a: any, b: any) => boolean
- Custom equality function for comparing modelValue against trueValue.
- falseIcon
- MDI icon shown when the control is unchecked/false.
- trueIcon
- MDI icon shown when the control is checked/true.
- multipleboolean
- inlinebooleanfalse
- Renders inline instead of block, useful for side-by-side controls.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- color
- Intent or custom color applied to the control icon and label.
- bgColor
- Background color applied to the ripple/wrapper area.
- hoverboolean | IStateEffectConfig
- hoverClassstring
- Controls the wrapper dimensions via density offset.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- 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
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- rippleboolean | { class: string }true
- Enables Material ripple effect on the control input zone.
API
Slots
Content slots exposed by this component.
- #default
- Replaces the wrapper content. Receives the full control state (model, colors, icon, event handlers).
- #label
- Custom label content replacing the default OrigamLabel.
- #input
- Replaces the native input element. Receives all input attributes and handlers. Falls back to icon + native input when not provided.
API
Emits
Events emitted by this component.
- @click:labelMouseEvent
- Fired when the user clicks the label area.
- @update:modelValueany
- Emitted when the user toggles the control. Carries the new value.
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 sub-components.
- Ref<string>
- Reactive CSS string generated by useStyle.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet. Called automatically on mount.
- () => void
- Removes the injected style sheet. Called automatically on unmount.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Default text/icon color.
- Color when the control is disabled.
- Color when the control is in error state.
- Opacity of the entire control when disabled.
- Density modifier. compact → -8px, comfortable → +8px.
- Transition duration for icon and color animations.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Space | Toggles the checkbox or selects the radio option. |
| Tab | Moves focus to the next interactive element. |
Notes
- A native <input type="checkbox|radio"> is always rendered (even when the input slot is customised). This ensures browser-native focus, keyboard handling and form participation.
- aria-checked is set automatically by the native input. For type="checkbox", aria-checked is forwarded explicitly via the :aria-checked binding.
- The label is wired to the input via for/id. Clicking the label toggles the control and fires click:label.
- When error=true, the label and icon adopt --origam-selection-control---color-error for visual feedback. No aria-invalid is set at this layer — use OrigamInput / form-level components for validation semantics.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- colorvar(--origam-color__text---primary)
- Default control color.
- colorvar(--origam-color__text---disabled)
- Color when disabled.
- numbervar(--origam-opacity---50)
- Opacity when disabled.
- dimension40px
- Base width of the ripple wrapper (before density offset).
- dimension40px
- Base height of the ripple wrapper.
- durationvar(--origam-motion__duration---medium)
- Transition duration for icon/color animations.
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.
Checkbox use case
Radio use case
Custom input slot
Ecosystem
Family
Components from the same folder that share conventions and often compose together.