Switch

Switches toggle the state of a single setting on or off.

Enabled

Disabled

Overview

Switches are selection controls that allow users to toggle a single setting between two states: on/off, show/hide, etc. They appear as a sliding toggle with a marker that moves between positions to indicate the current state.

Switches provide immediate feedback and typically take effect instantly when toggled, making them ideal for settings that users want to control in real-time without requiring form submission.

Usage

forge-switch toggles a single, independent setting on or off through checked, participates natively in form submission and validation (required, readonly, name, value), and supports dense, icon, and label-position. It’s the third of three selection controls: reach for a checkbox instead when a user can select zero, one, or many options from a list, or a radio button instead when exactly one option in a visible set must be chosen.

Rules

Use clear, non-neutral labels that describe what the control will do when the switch is on.

Match label text to switch state so turning the switch on activates the labeled feature, and turning it off deactivates it.

Use a switch for a setting that takes effect immediately, with no separate submit step.

Write a label that describes what happens when the switch is on — say it aloud with "on/off" appended and it should make sense.

Keep each switch independent of every other control on the screen.

Don't

Don't use a switch for an action that needs review or confirmation, like Save or Submit — use a button instead.

Don't use a switch for a setting with a neutral or indeterminate state — use a checkbox instead.

Don't use a switch for two opposing options, like list view vs. map view — use a button toggle instead.

Don't nest switches — use checkboxes instead so a parent control can show an indeterminate state.

Label position

Set label-position to control whether the label sits before or after the switch.

label-position controls whether the label sits before or after the switch.

<forge-switch>
  Off/On (default)
</forge-switch>
<forge-switch label-position="start">
  Off/On (start)
</forge-switch>

Dense

Set dense to reduce the switch’s size.

Dense reduces the switch's size.

<forge-switch dense>
  Dense
</forge-switch>

Icons

Pass custom icons through the icon-on and icon-off slots.

Custom icons passed through the icon-on and icon-off slots.

<forge-switch icon="both">
  <span>
    Off/On
  </span>
  <forge-icon slot="icon-off" name="close">
  </forge-icon>
  <forge-icon slot="icon-on" name="check">
  </forge-icon>
</forge-switch>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconCheck } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconCheck]);
</script>

Disabled and readonly

disabled excludes the switch from the form; readonly keeps it in the form but locks its value.

Disabled excludes the switch from the form; readonly keeps it in the form but locks its value.

<forge-switch disabled>
  Disabled
</forge-switch>
<forge-switch disabled checked>
  Disabled (checked)
</forge-switch>
<forge-switch readonly checked>
  Readonly
</forge-switch>

Switches toggle the state of a single setting on or off.

import "@tylertech/forge/switch";

Properties

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	Gets/sets whether the switch is checked or not.
`on`	`on`	`boolean`	`false`	Alias for `checked` _(deprecated)_. Gets/sets whether the switch is checked or not.
`selected`	`selected`	`boolean`	`false`	Alias for `checked` _(deprecated)_.
`defaultChecked`	`default-checked`	`boolean`	`false`	Gets/sets whether the switch is checked by default.
`defaultOn`	`default-on`	`boolean`	`false`	Alias for `defaultChecked` _(deprecated)_. Gets/sets whether the switch is checked by default.
`value`	`value`	`string`	`'on'`	Gets/sets the value of the switch.
`dense`	`dense`	`boolean`	`false`	Controls whether the switch is dense.
`disabled`	`disabled`	`boolean`	`false`	Controls whether the switch is disabled.
`required`	`required`	`boolean`	`false`	Controls whether the switch is required.
`readonly`	`readonly`	`boolean`	`false`	Controls whether the switch is readonly.
`icon`	`icon`	`SwitchIconVisibility`	`'both'`	Controls the presence of the off and on icons.
`labelPosition`	`label-position`	`SwitchLabelPosition`	`'end'`	Controls whether the label appears before or after the switch.

Events

Name	Type	Description
`change`	`Event`	Dispatches when the switch's value changes.
`forge-switch-change`	`CustomEvent<boolean>`	Dispatches when the switch's value changes.

CSS Parts

Name	Description
`::part(switch)`	Styles the switch container element.
`::part(track)`	Styles the track element.
`::part(handle)`	Styles the handle element.
`::part(icon-on)`	Styles the on icon element.
`::part(icon-off)`	Styles the off icon element.
`::part(label)`	Styles the label element.
`::part(state-layer)`	Styles the state layer root element.
`::part(focus-indicator)`	Styles the focus indicator root element.

CSS Custom Properties

Name	Description
`--forge-theme-primary`	The primary color of the switch.
`--forge-theme-on-primary`	The color of elements placed on top of the primary color (the handle icons for example).
`--forge-switch-handle-on-color`	The color of the handle in the switch's on state.
`--forge-switch-handle-off-color`	The color of the handle in the switch's off state.
`--forge-switch-handle-active-on-color`	The color of the handle when the switch is active (pressed) in its on state.
`--forge-switch-handle-active-off-color`	The color of the handle when the switch is active (pressed) in its off state.
`--forge-switch-handle-size`	The inline and block size of the handle.
`--forge-switch-handle-width`	The inline size of the handle.
`--forge-switch-handle-height`	The block size of the handle.
`--forge-switch-handle-scale`	The scale transformation applied to the handle.
`--forge-switch-handle-on-scale`	The scale transformation applied to the handle in the switch's on state.
`--forge-switch-handle-off-scale`	The scale transformation applied to the handle in the switch's off state.
`--forge-switch-handle-active-scale`	The scale transformation applied to the handle when the switch is active (pressed).
`--forge-switch-handle-active-on-scale`	The scale transformation applied to the handle when the switch is active (pressed) in its on state.
`--forge-switch-handle-active-off-scale`	The scale transformation applied to the handle when the switch is active (pressed) in its off state.
`--forge-switch-handle-shape`	The shape of the handle.
`--forge-switch-handle-elevation`	The handle's shadow.
`--forge-switch-handle-on-elevation`	The handle's shadow in the switch's on state.
`--forge-switch-handle-off-elevation`	The handle's shadow in the switch's off state.
`--forge-switch-handle-active-elevation`	The handle's shadow when the switch is active (pressed).
`--forge-switch-handle-active-on-elevation`	The handle's shadow when the switch is active (pressed) in its on state.
`--forge-switch-handle-active-off-elevation`	The handle's shadow when the switch is active (pressed) in its off state.
`--forge-switch-track-on-color`	The color of the track in the switch's on state.
`--forge-switch-track-off-color`	The color fo the track in the switch's off state.
`--forge-switch-track-active-on-color`	The color of the track when the switch is active (pressed) in its on state.
`--forge-switch-track-active-off-color`	The color fo the track when the switch is active (pressed) in its off state.
`--forge-switch-track-width`	The inline size of the track.
`--forge-switch-track-height`	The block size of the track.
`--forge-switch-track-shape`	The shape of the track.
`--forge-switch-track-border-width`	The width of the track border.
`--forge-switch-track-on-border-width`	The width of the track border in the switch's on state.
`--forge-switch-track-off-border-width`	The width of the track border in the switch's off state.
`--forge-switch-track-active-on-border-width`	The width of the track border when the switch is active (pressed) in its on state.
`--forge-switch-track-active-off-border-width`	The width of the track border when the switch is active (pressed) in its off state.
`--forge-switch-track-border-color`	The color of the track border.
`--forge-switch-track-on-border-color`	The color of the track border in the switch's on state.
`--forge-switch-track-off-border-color`	The color of the track border in the switch's off state.
`--forge-switch-track-active-on-border-color`	The color of the track border when the switch is active (pressed) in its on state.
`--forge-switch-track-active-off-border-color`	The color of the track border when the switch is active (pressed) in its off state.
`--forge-switch-icon-color`	The color of the handle icons.
`--forge-switch-icon-on-color`	The color of the handle icon in the switch's on state.
`--forge-switch-icon-off-color`	The color of the handle icon in the switch's off state.
`--forge-switch-icon-active-on-color`	The color of the handle icon when the switch is active (pressed) in its on state.
`--forge-switch-icon-active-off-color`	The color of the handle icon when the switch is active (pressed) in its off state.
`--forge-switch-icon-size`	The size of the handle icon.
`--forge-switch-icon-on-size`	The size of the handle icon in the switch's on state.
`--forge-switch-icon-off-size`	The size of the handle icon in the switch's off state.
`--forge-switch-icon-scale`	The scale transformation applied to the handle icons.
`--forge-switch-icon-on-scale`	The scale transformation applied to the handle icons in the switch's on state.
`--forge-switch-icon-off-scale`	The scale transformation applied to the handle icons in the switch's off state.
`--forge-switch-icon-active-on-scale`	The scale transformation applied to the handle icons when the switch is active (pressed) in its on state.
`--forge-switch-icon-active-off-scale`	The scale transformation applied to the handle icons when the switch is active (pressed) in its off state.
`--forge-switch-gap`	The space between the switch and label.
`--forge-switch-justify`	How the switch and label are distributed along their main axis.
`--forge-switch-align`	How the switch and label are distributed along their cross axis.
`--forge-switch-direction`	Whether the switch and label are arranged along the inline or block axis.
`--forge-switch-state-layer-size`	The inline and block size of the handle's state layer.
`--forge-switch-state-layer-width`	The inline size of the handle's state layer.
`--forge-switch-state-layer-height`	The block size of the handle's state layer.
`--forge-switch-state-layer-on-color`	The color of the handle's state layer when the switch is in its on state.
`--forge-switch-state-layer-off-color`	The color of the handle's state layer when the switch is in its off state.
`--forge-switch-state-layer-dense-size`	The inline and block size of the handle's state layer when the dense switch is used.
`--forge-switch-state-layer-dense-width`	The inline size of the handle's state layer when the dense switch is used.
`--forge-switch-state-layer-dense-height`	The block size of the handle's state layer when the dense switch is used.
`--forge-switch-disabled-opacity`	The opacity of the switch when disabled.
`--forge-switch-animation-duration`	The duration of animations.
`--forge-switch-animation-timing`	The timing function used in most animations.
`--forge-switch-active-animation-timing`	The timing function used in active state animations.

Methods

Name	Returns	Description
`toggle(force)`	`void`	Toggles the switch on or off.

Keyboard interaction

Ensure the switch is reachable by the tab key and can be toggled with the keyboard, not just a pointer.

The switch automatically applies role="switch" and aria-checked to the input, so assistive technology announces its state without any extra wiring.