Switch

A control that lets the user toggle between checked and not checked.

import { Label } from "@/components/ui/label"
import { HStack } from "@/components/ui/stack"
import { Switch } from "@/components/ui/switch"

export default function SwitchDemo() {
  return (
    <HStack gap={2} align="center">
      <Switch id="focus-mode" name="focus-mode" />
      <Label htmlFor="focus-mode">Focus mode</Label>
    </HStack>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/switch

Needs the arene setup first.

Usage

import { Label } from "@/components/ui/label"
import { HStack } from "@/components/ui/stack"
import { Switch } from "@/components/ui/switch"
<HStack gap={2} align="center">
  <Switch id="focus-mode" />
  <Label htmlFor="focus-mode">Focus mode</Label>
</HStack>

Match the label's htmlFor to the switch's id, or wrap the switch in the label. A switch takes effect the moment it is flipped, so it needs no submit button beside it. Use a Checkbox for a value that is saved with a form.

The thumb travels on inset-inline-start, so it moves toward the inline end in a right-to-left document.

Checked state

Use defaultChecked for an uncontrolled switch, or checked and onCheckedChange to control it.

const [enabled, setEnabled] = useState(false)

return <Switch checked={enabled} onCheckedChange={setEnabled} />

Give the switch a name to submit it with a form. Base UI renders a hidden <input type="checkbox"> beside the control, and that input carries the value.

Description

Put the switch in a horizontal Field and a FieldContent beside it to add a line of helper text under the label.

Focus mode follows you to every device you are signed in on.

import * as stylex from "@stylexjs/stylex"
import { Field, FieldContent, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  field: { maxWidth: width.sm },
})

export default function SwitchDescription() {
  return (
    <Field orientation="horizontal" xstyle={styles.field}>
      <FieldContent>
        <FieldLabel>Sync across devices</FieldLabel>
        <FieldDescription>
          Focus mode follows you to every device you are signed in on.
        </FieldDescription>
      </FieldContent>
      <Switch id="switch-focus-mode" />
    </Field>
  )
}

Choice card

Wrap a whole Field in a FieldLabel to turn the row into a card, and pass checked to style the cards that are on.

"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
} from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  group: { maxWidth: width.sm },
})

const settings = [
  {
    id: "share",
    title: "Sync across devices",
    description: "Focus mode follows you to every device you are signed in on.",
  },
  {
    id: "notifications",
    title: "Tell collaborators",
    description: "Let your lab know when you turn focus mode on or off.",
  },
]

export default function SwitchChoiceCard() {
  const [enabled, setEnabled] = useState<Record<string, boolean>>({ notifications: true })

  return (
    <FieldGroup gap={3} xstyle={styles.group}>
      {settings.map((setting) => (
        <FieldLabel
          key={setting.id}
          htmlFor={`setting-${setting.id}`}
          checked={enabled[setting.id] ?? false}
        >
          <Field orientation="horizontal">
            <FieldContent>
              <FieldTitle>{setting.title}</FieldTitle>
              <FieldDescription>{setting.description}</FieldDescription>
            </FieldContent>
            <Switch
              id={`setting-${setting.id}`}
              checked={enabled[setting.id] ?? false}
              onCheckedChange={(checked) =>
                setEnabled((current) => ({ ...current, [setting.id]: checked }))
              }
            />
          </Field>
        </FieldLabel>
      ))}
    </FieldGroup>
  )
}

FieldLabel does not read the switch's state, so checked is a prop you set from the same value you give the switch. That makes the card a controlled switch.

Disabled

Set disabled on Field to disable its control and dim its label, or on a bare control directly.

import * as stylex from "@stylexjs/stylex"
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"
import { textStyles } from "@/components/ui/text"

const styles = stylex.create({
  group: { width: "fit-content" },
})

export default function SwitchDisabled() {
  return (
    <FieldGroup gap={3} xstyle={styles.group}>
      <Field orientation="horizontal" disabled>
        <Switch id="switch-disabled-off" />
        <FieldLabel xstyle={textStyles.weights.normal}>Off</FieldLabel>
      </Field>
      <Field orientation="horizontal" disabled>
        <Switch id="switch-disabled-on" defaultChecked />
        <FieldLabel xstyle={textStyles.weights.normal}>On</FieldLabel>
      </Field>
    </FieldGroup>
  )
}

Invalid

Set invalid on Field to style its control, or aria-invalid on a bare control. The examples show both.

import { Switch } from "@/components/ui/switch"
import { Field, FieldLabel, FieldError } from "@/components/ui/field"
import { Label } from "@/components/ui/label"
import { VStack } from "@/components/ui/stack"

export default function SwitchInvalid() {
  return (
    <VStack gap={5} width="100%" maxWidth="24rem">
      <VStack gap={2}>
        <Label htmlFor="switch-invalid-bare">Agree to the usage policy</Label>
        <Switch
          id="switch-invalid-bare"
          aria-invalid
          aria-describedby="switch-invalid-bare-error"
        />
        <FieldError id="switch-invalid-bare-error">
          Agree to the usage policy to continue.
        </FieldError>
      </VStack>
      <Field invalid>
        <FieldLabel>Agree to the usage policy</FieldLabel>
        <Switch />
        <FieldError>Agree to the usage policy to continue.</FieldError>
      </Field>
    </VStack>
  )
}

Size

Set size to make the switch smaller. The thumb and the travel follow the track, so a sm switch needs no other change.

import * as stylex from "@stylexjs/stylex"
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"
import { textStyles } from "@/components/ui/text"

const styles = stylex.create({
  group: { width: "fit-content" },
})

export default function SwitchSize() {
  return (
    <FieldGroup gap={3} xstyle={styles.group}>
      <Field orientation="horizontal">
        <Switch id="switch-size-sm" size="sm" defaultChecked />
        <FieldLabel xstyle={textStyles.weights.normal}>Small</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch id="switch-size-default" size="default" defaultChecked />
        <FieldLabel xstyle={textStyles.weights.normal}>Default</FieldLabel>
      </Field>
    </FieldGroup>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Switch wraps the Base UI Switch primitive and accepts its props. See the Base UI reference.

Switch

PropTypeDefault
size"sm" | "default""default"
checkedboolean—
defaultCheckedbooleanfalse
onCheckedChange(checked, details) => void—
namestring—
valuestring—
disabledbooleanfalse
readOnlybooleanfalse
requiredbooleanfalse
aria-invalidboolean—
idstring—
inputRefRef<HTMLInputElement>—
xstyleStyleXStyles—
styleCSSProperties—
classNamestring—

The root is a <button role="switch">. Base UI renders a hidden <input> beside it that carries id, name and value. A label's htmlFor and a form submission reach the control through that input. The component renders the thumb. There is no SwitchThumb part to place.

switchStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
rootThe track: shape, fill, hit area
sizesThe sm and default track sizes, keyed by name
checkedThe primary fill and its sheen
disabledThe dimmed, non-interactive state
invalidThe destructive border and ring
thumbThe thumb at rest and the transition it travels on
thumbCheckedThe thumb's far end of the travel and its fill

A size sets --arene-switch-thumb, which the thumb reads for its width, height and the distance it moves. Override that property to resize a switch without adding a size.

root carries no focus ring. The ring, disabled and invalid all come from states in theme/states.ts, and the ring reads a resting border colour from --arene-border-color. The switch leaves that property unset, so the track's border stays transparent until focus colours it.

Data attributes

AttributeOnEffect
data-slot="switch"the trackTargets the control
data-slot="switch-thumb"the thumbTargets the moving part
data-sizethe trackMirrors the size prop
data-checked, data-uncheckedtrack, thumbBase UI writes them
data-disabled, data-readonly, data-requiredtrack, thumbBase UI writes them