SelectionControl

Form & Input
stable

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…

unchecked

Rendering the live preview…

checked

Rendering the live preview…

radio

Rendering the live preview…

error

Rendering the live preview…

disabled

Structure

Anatomy

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

Anatomy of OrigamSelectionControlSchematic of the SelectionControl component with 5 numbered parts. ✓ Label text 1 2 3 4 5
Anatomy of <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.

label
string
Label text displayed next to the control via OrigamLabel.
trueValue
any
Value emitted when the control is checked.
falseValue
any
Value emitted when the control is unchecked.
value
any
Value for group context. Used by SelectionControlGroup to determine membership.
required
boolean
false
Marks the control as required.
disabled
boolean
false
Disables the control.
error
string | boolean
false
Puts the control in error state. Changes label and icon color.
name
string
Name attribute for the native input. Groups radio buttons for browser behaviour.
readonly
boolean
false
Makes the control read-only (no interaction).
type
string
'checkbox'
Native input type. Usually checkbox or radio. Determines ARIA semantics.
modelValue
any
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.
multiple
boolean
inline
boolean
false
Renders inline instead of block, useful for side-by-side controls.
id
string
class
string | Array<string> | object
style
string | 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.
hover
boolean | IStateEffectConfig
hoverClass
string
density
'default'
Controls the wrapper dimensions via density offset.
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
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
rounded
boolean | number | string | TRounded | null | undefined
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
elevation
TElevation
ripple
boolean | { 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:label
MouseEvent
Fired when the user clicks the label area.
@update:modelValue
any
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

checkbox
radio

Keyboard interactions

Keyboard interactions
KeyAction
SpaceToggles the checkbox or selects the radio option.
TabMoves 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.

Source
color
var(--origam-color__text---primary)
Default control color.
color
var(--origam-color__text---disabled)
Color when disabled.
number
var(--origam-opacity---50)
Opacity when disabled.
dimension
40px
Base width of the ripple wrapper (before density offset).
dimension
40px
Base height of the ripple wrapper.
duration
var(--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

vue

Radio use case

vue

Custom input slot

vue

Ecosystem

Family

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