Switch

Class: FxSwitch · Tag: <fx-switch> · Mixins: Animatable

The <fx-switch> component is a premium, segmented multi-state selector featuring a fluid sliding thumb. It supports two or more custom states, optional icons, and both horizontal and vertical layouts for an elegant, tactile user experience.

Installation

import '@salsafx/ui';

Interactive preview of the main variants:

Binary Toggle

Tri-State

With Icons

Basic Usage

Binary Toggle Switch (On/Off Default)

When rendered with no states provided, <fx-switch> defaults to a standard binary On/Off toggle. Click the switch below to toggle it!

Active ID: off

<fx-switch active-id="off"></fx-switch>

Tri-State Mode Selector

Pass <fx-switch-state> child tags to create custom configurations. Click the state buttons below to toggle through active states — note how the highlighted thumb transitions smoothly across the switch track!

Active ID: medium

<fx-switch active-id="auto" theme="light">
    <fx-switch-state
        value="off"
        label="Manual Off"
        background-color="#ef4444"
    ></fx-switch-state>
    <fx-switch-state
        value="auto"
        label="Auto Control"
        background-color="#10b981"
    ></fx-switch-state>
    <fx-switch-state
        value="force"
        label="Force Flush"
        background-color="#f59e0b"
    ></fx-switch-state>
</fx-switch>

Segmented Control with Icons

Set the optional icon attribute to a Font Awesome class string. Without icon, the segment shows only the label.

<fx-switch active-id="performance" state-width="105">
    <fx-switch-state
        value="eco"
        label="Eco"
        icon="fa-solid fa-leaf"
    ></fx-switch-state>
    <fx-switch-state
        value="standard"
        label="Standard"
        icon="fa-solid fa-sun"
    ></fx-switch-state>
    <fx-switch-state
        value="performance"
        label="Performance"
        icon="fa-solid fa-gauge-high"
    ></fx-switch-state>
    <fx-switch-state
        value="custom"
        label="Custom"
        icon="fa-solid fa-shield-halved"
    ></fx-switch-state>
</fx-switch>

API Reference

`<fx-switch>` Properties & Attributes

Property	Attribute	Type	Default	Description
`activeId`	`active-id`	`String`	`""`	ID of the currently selected state.
`orientation`	`orientation`	`String`	`"horizontal"`	Orientation of the switch (“horizontal” or “vertical”).
`theme`	`theme`	`"light"` \| `"dark"`	`"dark"`	Color theme preset (“light” or “dark”).
`foregroundColor`	`foreground-color`	`String`	`"#ffffff"`	Default active text and icon color.
`backgroundColor`	`background-color`	`String`	`"#3b82f6"`	Default active sliding thumb background color.
`stateWidth`	`state-width`	`Number` \| `String`	`72`	Width of each state segment.
`isAnimated`	`is-animated`	`Boolean`	`true`	Enables fluid, hardware-accelerated sliding transitions.
`disabled`	`disabled`	`Boolean`	`false`	Disables the control and prevents user interaction.
`states`	—	`Array`	`[]`	Array of state configurations.

`<fx-switch-state>` Properties

Property	Attribute	Type	Default	Description
`value`	`value`	`String`	`""`	Unique state identifier value.
`label`	`label`	`String`	`""`	State text label.
`icon`	`icon`	`String`	`""`	Optional Font Awesome icon class name.
`foregroundColor`	`foreground-color`	`String`	`""`	Active state text and icon color override.
`backgroundColor`	`background-color`	`String`	`""`	Active state thumb background color override.
`disabled`	`disabled`	`Boolean`	`false`	Disables only this state segment.

Icons are placed so that page-level stylesheets apply. With a states array, pass an icon-font class list or a .svg path on each item (e.g. icon: 'fa-solid fa-leaf').

Events

Name	Detail	Description
`change`	`{ id: String, state: Object }`	Emitted when a state is clicked. `id` contains the new active ID.

CSS Custom Properties

Property	Default	Description
`--fx-switch-track-color`	`#ffffff`	Background of the switch casing track.
`--fx-switch-border-color`	`#e5e7eb`	Casing outer boundary frame line.
`--fx-switch-border-radius`	`16px`	Outer track corner radius.
`--fx-switch-btn-border-radius`	`12px`	Active thumb corner radius.
`--fx-switch-padding`	`4px`	Padding space between casing border and buttons.
`--fx-switch-font-size`	`0.8125rem`	Text size of the state labels.
`--fx-switch-icon-size`	`1.125rem`	Font Awesome icon size.
`--fx-switch-icon-gap`	`6px`	Gap between icon and label.
`--fx-switch-text-inactive`	`#374151`	Color of inactive toggle buttons.
`--fx-switch-divider-color`	`#e5e7eb`	Divider between adjacent inactive segments.
`--fx-switch-background-active`	`#3b82f6`	Default sliding thumb background (if state overrides are absent).

Object Hierarchy

classDiagram
    direction TB
    class FxElement
    class FxSwitch

    FxElement <|-- FxSwitch : Animatable