SwitchTrack

Form & Input
stable

The rounded rail behind the Switch thumb. Owns its visual surface (background, inset variant, error state) and exposes slots for content shown on each side of the rail.

Preview

Rendering the live preview…

off

Rendering the live preview…

on

Rendering the live preview…

inset off

Rendering the live preview…

inset on

Rendering the live preview…

disabled

Rendering the live preview…

error

Structure

Anatomy

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

Anatomy of OrigamSwitchTrackSchematic of the SwitchTrack component with 4 numbered internal parts. origam-switch-track--dirty true false 1 2 3 4
Anatomy of <origam-switch-track> — 4 internal parts. The pill-shaped rail paints the background; the __true / __false halves reveal or hide on each side; the overlay slot sits on top.
1.origam-switch-track
Root element. Pill-shaped rail with border-radius: 9999px. Carries state modifiers: --dirty (ON), --disabled, --readonly, --error, --inset.
2.origam-switch-track__true
Left half — hosts the #track.true slot. Visible (opacity: 1) when modelValue is true, hidden (opacity: 0) when false. Uses margin-inline-end: auto to push to the left.
3.origam-switch-track__false
Right half — hosts the #track.false slot. Visible when modelValue is false, hidden when true. Uses margin-inline-start: auto to push to the right.
4(overlay slot)
#overlay slot host rendered after the half-labels. Positioned freely inside the track (absolute positioning is the consumer's responsibility).

API

Props

All props accepted by this component, with their type, default value and description.

modelValue
boolean
false
Whether the switch is currently ON. Drives the --dirty modifier class that reveals the track.true slot and hides the track.false slot.
isValid
boolean | null
null
Validation state forwarded from the surrounding OrigamInput. Exposed to slot consumers via the slot prop.
disabled
boolean
false
Disabled state. Applies --disabled modifier and blocks click propagation. bgColor is ignored when disabled.
readonly
boolean
false
Readonly state. Keeps the visual appearance interactive but blocks click events. Applies --readonly modifier.
error
string | boolean
false
Error state. Overrides the rail background with the danger feedback token. bgColor is ignored when error is true.
inset
boolean
false
Inset (Material 3 style) variant. Renders a taller and wider pill rail with a larger font size.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
color
Foreground colour intent. Exposed to slot consumers (e.g. an icon inside track.true) but does NOT paint the track rail itself — use bgColor for that.
bgColor
Background colour of the track rail. Ignored when disabled or error is true (state tokens take precedence).
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

API

Slots

Content slots exposed by this component.

#track.true
Content shown on the left side of the rail (the ON side). Hidden via opacity when modelValue is false.
#track.false
Content shown on the right side of the rail (the OFF side). Hidden via opacity when modelValue is true.
#overlay
Free-form overlay rendered inside the track after the half-labels. Used by OrigamSwitch to host a linear progress bar when loading, or by consumers for decorative effects.
#default

API

Emits

Events emitted by this component.

@click
MouseEvent
Fired when the track is clicked (not blocked by disabled / readonly). stopPropagation and preventDefault are called before emitting so the parent SelectionControl handles toggle forwarding without double-toggling.

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 a child component.
Ref<string>
Reactive CSS string generated by useStyle from the computed track styles.
string
Unique style-sheet ID for this instance.
() => void
Injects the computed style sheet into the document. Called automatically on mount.
() => void
Removes the injected style sheet. Called automatically on unmount.
Ref<boolean>
True once the style sheet has been injected into the DOM.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

Rail background colour in OFF state. Overridden by bgColor prop when set.
Corner radius of the track rail (pill shape).
Height of the standard (non-inset) track.
Minimum width of the standard (non-inset) track.
Height of the track in inset variant.
Minimum width of the track in inset variant.
Rail background in disabled ON state.
Opacity applied to the entire track in disabled state.

Inclusion

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

Notes

  • SwitchTrack is a purely visual sub-component. All ARIA semantics (role="switch", aria-checked, aria-label) live on the hidden <input> or the SelectionControl root inside OrigamSwitch — not on the track itself.
  • Under forced-colors: active a 1px border is rendered and colour transitions are disabled so the track remains distinguishable from the background. The ON state paints the track highlight colour.
  • The background-color transition is removed under prefers-reduced-motion: reduce.

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
dimension
44px
Width of the standard track.
dimension
24px
Height of the standard track.
dimension
var(--origam-radius---full)
Pill border-radius of the track.
color
color-mix(in srgb, var(--origam-color__text---primary) 60%, var(--origam-color__surface---default))
Track background in OFF state.
color
var(--origam-color__action--primary---bg)
Track background in ON state.
color
var(--origam-color__feedback--danger---bg)
Track background in error 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 usage (inside a Switch)

vue

Custom track content slots

vue

Ecosystem

Family

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