SwitchTrack
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…
offRendering the live preview…
onRendering the live preview…
inset offRendering the live preview…
inset onRendering the live preview…
disabledRendering the live preview…
errorStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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.trueslot. Visible (opacity: 1) whenmodelValueis true, hidden (opacity: 0) when false. Usesmargin-inline-end: autoto push to the left. - 3.origam-switch-track__false
- Right half — hosts the
#track.falseslot. Visible whenmodelValueis false, hidden when true. Usesmargin-inline-start: autoto push to the right. - 4(overlay slot)
#overlayslot 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.
- modelValuebooleanfalse
- Whether the switch is currently ON. Drives the --dirty modifier class that reveals the track.true slot and hides the track.false slot.
- isValidboolean | nullnull
- Validation state forwarded from the surrounding OrigamInput. Exposed to slot consumers via the slot prop.
- disabledbooleanfalse
- Disabled state. Applies --disabled modifier and blocks click propagation. bgColor is ignored when disabled.
- readonlybooleanfalse
- Readonly state. Keeps the visual appearance interactive but blocks click events. Applies --readonly modifier.
- errorstring | booleanfalse
- Error state. Overrides the rail background with the danger feedback token. bgColor is ignored when error is true.
- insetbooleanfalse
- Inset (Material 3 style) variant. Renders a taller and wider pill rail with a larger font size.
- idstring
- classstring | Array<string> | object
- stylestring | 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).
- 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
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.
- @clickMouseEvent
- 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.
- dimension44px
- Width of the standard track.
- dimension24px
- Height of the standard track.
- dimensionvar(--origam-radius---full)
- Pill border-radius of the track.
- colorcolor-mix(in srgb, var(--origam-color__text---primary) 60%, var(--origam-color__surface---default))
- Track background in OFF state.
- colorvar(--origam-color__action--primary---bg)
- Track background in ON state.
- colorvar(--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)
Custom track content slots
Ecosystem
Family
Components from the same folder that share conventions and often compose together.