Documentation Playground
Skip to content
Docs

Switch

Toggle switch alternative to the checkbox. 
<.switch id="switch-hero" default_checked />

API Reference

This component wraps the Switch primitive and supports common margin props.

Prop Type Default Description
checked boolean nil Controlled checked state. Can be true or false.
class string nil Additional CSS classes to add to the element.
color string — Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky.
default_checked boolean false Initial checked state. If true, switch starts checked.
disabled boolean false Whether the switch is disabled.
form string nil The form ID this switch belongs to.
high_contrast boolean — Whether to increase color contrast with the background.
id string nil
m any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mb any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
ml any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mr any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mt any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mx any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
my any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
name string nil Form name attribute.
on_checked_change string nil LiveView event to push when the checked state changes.
required boolean false Whether the switch is required.
size string "2" Switch size from 1 to 3. Controls overall dimensions and thumb size.
style string ""
value string nil Form value attribute.
variant string "surface" Visual style variant. One of 'surface', 'classic', or 'soft'.
checked Controlled checked state. Can be true or false.
Type boolean Default nil
class Additional CSS classes to add to the element.
Type string Default nil
color Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky.
Type string Default —
default_checked Initial checked state. If true, switch starts checked.
Type boolean Default false
disabled Whether the switch is disabled.
Type boolean Default false
form The form ID this switch belongs to.
Type string Default nil
high_contrast Whether to increase color contrast with the background.
Type boolean Default —
id
Type string Default nil
m Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mb Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
ml Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mr Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mt Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mx Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
my Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
name Form name attribute.
Type string Default nil
on_checked_change LiveView event to push when the checked state changes.
Type string Default nil
required Whether the switch is required.
Type boolean Default false
size Switch size from 1 to 3. Controls overall dimensions and thumb size.
Type string Default "2"
style
Type string Default ""
value Form value attribute.
Type string Default nil
variant Visual style variant. One of 'surface', 'classic', or 'soft'.
Type string Default "surface"

Examples

Size

Use the size prop to control the size of the switch.

<.flex align="center" gap="2">
  <.switch id="switch-size-1" size="1" default_checked /><.switch
    id="switch-size-2"
    size="2"
    default_checked
  /><.switch id="switch-size-3" size="3" default_checked />
</.flex>

Variant

Use the variant prop to control the visual style of the switch.

<.flex gap="2">
  <.flex direction="column" gap="3">
    <.switch id="switch-variant-surface-off" variant="surface" /><.switch
      id="switch-variant-classic-off"
      variant="classic"
    /><.switch id="switch-variant-soft-off" variant="soft" />
  </.flex>
  <.flex direction="column" gap="3">
    <.switch id="switch-variant-surface-on" variant="surface" default_checked /><.switch
      id="switch-variant-classic-on"
      variant="classic"
      default_checked
    /><.switch id="switch-variant-soft-on" variant="soft" default_checked />
  </.flex>
</.flex>

Color

Use the color prop to assign a specific accent color.

<.flex gap="2">
  <.switch id="switch-color-indigo" color="indigo" default_checked /><.switch
    id="switch-color-cyan"
    color="cyan"
    default_checked
  /><.switch id="switch-color-orange" color="orange" default_checked /><.switch
    id="switch-color-crimson"
    color="crimson"
    default_checked
  />
</.flex>

High-contrast

Use the high_contrast prop to increase color contrast in light mode.

<.grid rows="2" gap_x="2" gap_y="3" display="inline-grid" flow="column">
  <.switch id="switch-hc-indigo" color="indigo" default_checked /><.switch
    id="switch-hc-indigo-contrast"
    color="indigo"
    default_checked
    high_contrast
  /><.switch id="switch-hc-cyan" color="cyan" default_checked /><.switch
    id="switch-hc-cyan-contrast"
    color="cyan"
    default_checked
    high_contrast
  /><.switch id="switch-hc-orange" color="orange" default_checked /><.switch
    id="switch-hc-orange-contrast"
    color="orange"
    default_checked
    high_contrast
  /><.switch id="switch-hc-crimson" color="crimson" default_checked /><.switch
    id="switch-hc-crimson-contrast"
    color="crimson"
    default_checked
    high_contrast
  /><.switch id="switch-hc-gray" color="gray" default_checked /><.switch
    id="switch-hc-gray-contrast"
    color="gray"
    default_checked
    high_contrast
  />
</.grid>

Alignment

Composing Switch within Text automatically centers it with the first line of text.

<.flex direction="column" gap="3">
  <.text as="label" size="2">
    <.flex gap="2"><.switch id="switch-align-1" size="1" default_checked /> Sync settings</.flex>
  </.text>
  <.text as="label" size="3">
    <.flex gap="2"><.switch id="switch-align-2" size="2" default_checked /> Sync settings</.flex>
  </.text>
  <.text as="label" size="4">
    <.flex gap="2"><.switch id="switch-align-3" size="3" default_checked /> Sync settings</.flex>
  </.text>
</.flex>

It is automatically well-aligned with multi-line text too.

Disabled

Use the native disabled attribute to create a disabled switch.

<.flex direction="column" gap="2">
  <.text as="label" size="2">
    <.flex gap="2"><.switch id="switch-disabled-off" size="1" /> Off</.flex>
  </.text>
  <.text as="label" size="2">
    <.flex gap="2"><.switch id="switch-disabled-on" size="1" default_checked /> On</.flex>
  </.text>
  <.text as="label" size="2" color="gray">
    <.flex gap="2"><.switch id="switch-disabled-off-locked" size="1" disabled /> On</.flex>
  </.text>
  <.text as="label" size="2" color="gray">
    <.flex gap="2">
      <.switch id="switch-disabled-on-locked" size="1" disabled default_checked /> Off
    </.flex>
  </.text>
</.flex>
← Spinner Tab Nav →