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.

Aperçu

Rendu de l’aperçu en cours…

off

Rendu de l’aperçu en cours…

on

Rendu de l’aperçu en cours…

inset off

Rendu de l’aperçu en cours…

inset on

Rendu de l’aperçu en cours…

disabled

Rendu de l’aperçu en cours…

error

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

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

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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

Emplacements de contenu exposés par ce composant.

#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

Événements émis par ce composant.

@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

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 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.

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.

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

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

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.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

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.

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 usage (inside a Switch)

vue

Custom track content slots

vue

Écosystème

Famille

Composants du même dossier qui partagent les conventions et se composent souvent ensemble.