Skip to content
Browse documentation
whisk/ui

Switch

Turn a setting on or off.

Overview

Switch is a native on-or-off control with switch semantics. It changes a local checked value; the application decides whether that change takes effect, is saved, or needs confirmation.

Coming from another library?
Use native onChange, not onCheckedChange. Use a stable setting label, not a state label such as On or Off; checked accepts only a boolean.

Use when

A clearly labelled setting can be turned on or off.

Use instead

Use Checkbox for consent or agreement, or for choices the user reviews before submitting. Use Radio or SegmentedControl for more than two states.

Usage

import { Switch } from "@smoothie-framework/whisk-react";

<Switch
  name="notifications"
  label="Enable notifications"
  defaultChecked
/>

Examples

Sizes

Match the switch size to the density of the surrounding controls.

import { Stack, Switch } from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <Switch size="sm" label="Small" defaultChecked />
  <Switch size="md" label="Medium" defaultChecked />
  <Switch size="lg" label="Large" defaultChecked />
</Stack>

Forms

Use react-hook-form to read both switch values. On and off are both valid settings.

Notification settings

Choose your notification settings.

import { useState } from "react";
import { useForm } from "react-hook-form";
import { Box, Button, Stack, Switch, Text } from "@smoothie-framework/whisk-react";

type NotificationValues = { weeklyReports: boolean; productUpdates: boolean };

export function NotificationSettingsForm() {
  const [result, setResult] = useState("Choose your notification settings.");
  const { register, handleSubmit } = useForm<NotificationValues>({
    defaultValues: { weeklyReports: true, productUpdates: false },
  });
  const onSubmit = (values: NotificationValues) => {
    setResult(`Saved: weekly reports ${values.weeklyReports ? "on" : "off"}, product updates ${values.productUpdates ? "on" : "off"}.`);
  };

  return (
    <Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
      <Stack gap={3}>
        <Stack gap={2}>
          <Text weight="semibold">Notification settings</Text>
          <Switch label="Weekly reports" {...register("weeklyReports")} />
          <Switch label="Product updates" {...register("productUpdates")} />
        </Stack>
        <Button type="submit">Save settings</Button>
        <Text color="subtle" aria-live="polite">{result}</Text>
      </Stack>
    </Box>
  );
}

Controlled

Use checked and onChange when application state owns the setting.

Notifications: on

import { useState } from "react";
import { Stack, Switch, Text } from "@smoothie-framework/whisk-react";

export function NotificationSwitch() {
  const [enabled, setEnabled] = useState(true);
  return (
    <Stack gap={2}>
      <Switch
        checked={enabled}
        label="Email notifications"
        onChange={(event) => setEnabled(event.currentTarget.checked)}
      />
      <Text color="subtle" aria-live="polite">
        Notifications: {enabled ? "on" : "off"}
      </Text>
    </Stack>
  );
}

Settings list

Use aligned rows when several independent settings share one surface.

Weekly reports

A summary of workspace activity every Monday.

Product updates

News about new features and improvements.

Security alerts

Important account and sign-in activity.

import { Box, Divider, Stack, StackRow, Switch, Text } from "@smoothie-framework/whisk-react";

<Box width="full" border="sm" borderColor="borderSubtle" rounded="md">
  <Stack gap={0}>
    <Box padding={4}>
      <StackRow align="center" justify="between" gap={4}>
        <Stack gap={1}>
          <Text id="weekly-reports-title" weight="semibold">Weekly reports</Text>
          <Text id="weekly-reports-description" color="subtle">
            A summary of workspace activity every Monday.
          </Text>
        </Stack>
        <Switch
          aria-labelledby="weekly-reports-title"
          aria-describedby="weekly-reports-description"
          defaultChecked
        />
      </StackRow>
    </Box>
    <Divider decorative />
    <Box padding={4}>
      <StackRow align="center" justify="between" gap={4}>
        <Stack gap={1}>
          <Text id="product-updates-title" weight="semibold">Product updates</Text>
          <Text id="product-updates-description" color="subtle">
            News about new features and improvements.
          </Text>
        </Stack>
        <Switch
          aria-labelledby="product-updates-title"
          aria-describedby="product-updates-description"
        />
      </StackRow>
    </Box>
    <Divider decorative />
    <Box padding={4}>
      <StackRow align="center" justify="between" gap={4}>
        <Stack gap={1}>
          <Text id="security-alerts-title" weight="semibold">Security alerts</Text>
          <Text id="security-alerts-description" color="subtle">
            Important account and sign-in activity.
          </Text>
        </Stack>
        <Switch
          aria-labelledby="security-alerts-title"
          aria-describedby="security-alerts-description"
          defaultChecked
        />
      </StackRow>
    </Box>
  </Stack>
</Box>

Immediate save

Show pending, success, and failure feedback when a switch saves as soon as it changes. This demo fails when turning the setting off to show the error state.

import { useState } from "react";
import { Field, Stack, Switch, Text } from "@smoothie-framework/whisk-react";

export function DeliveryNotifications() {
  const [enabled, setEnabled] = useState(false);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState<string>();
  let status: string | undefined;
  if (saving) {
    status = "Saving delivery notifications…";
  } else if (enabled && error === undefined) {
    status = "Delivery notifications saved.";
  }

  return (
    <Stack gap={2}>
      <Field invalid={error !== undefined} error={error}>
        <Switch
          checked={enabled}
          disabled={saving}
          label="Delivery notifications"
          onChange={(event) => {
            const next = event.currentTarget.checked;
            const previous = enabled;
            setEnabled(next);
            setSaving(true);
            setError(undefined);
            setTimeout(() => {
              setSaving(false);
              if (!next) {
                setEnabled(previous);
                setError("Couldn't update delivery notifications. Try again.");
              }
            }, 800);
          }}
        />
      </Field>
      {status ? <Text color="subtle" aria-live="polite">{status}</Text> : null}
    </Stack>
  );
}

Disabled

Use disabled when the setting is unavailable. Its current value remains visible but cannot change.

Available on the Business plan.
import { Switch } from "@smoothie-framework/whisk-react";

<Switch
  defaultChecked
  disabled
  label="Audit log export"
  description="Available on the Business plan."
/>

Invalid

Use invalid with Field error feedback to explain what needs attention.

A notification is sent after each scheduled report.
Couldn't update delivery notifications. Try again.
import { Field, Switch } from "@smoothie-framework/whisk-react";

<Field invalid error="Couldn't update delivery notifications. Try again.">
  <Switch
    invalid
    label="Enable delivery notifications"
    description="A notification is sent after each scheduled report."
  />
</Field>

Read-only

Use readOnly when the setting must stay visible but cannot change here.

Managed by your organization.
import { Switch } from "@smoothie-framework/whisk-react";

<Switch
  defaultChecked
  readOnly
  label="Automatic backups"
  description="Managed by your organization."
/>

Props

Component props

PropTypeDefaultDescription
checkedbooleanfalseControl the native checked value. Keep it in sync through native onChange.
defaultCheckedbooleanfalseInitialize the native checked value without controlling later changes.
labelReactNodenoneName the stable setting; do not change the label with the current state.
descriptionReactNodenoneExplain what changing the setting does when the label alone is not enough.
namestringnoneName the checked value for native form submission.
valuestringonSet the value submitted when the switch is checked.
formstringnoneAssociate the switch with a native form by ID.
requiredbooleanfalseRequire the switch to be on before native form submission. Prefer Checkbox for consent or agreement.
sizesm | md | lgmdChoose the switch's shared visual size without changing its semantics.
invalidbooleanfalseExpose invalid state; pair it with Field error feedback that explains how to recover.
readOnlybooleanfalseKeep a visible setting from changing in the current context.
disabledbooleanfalsePrevent interaction while the setting is unavailable or saving.
onChangenative input change handlernoneHandle a native event and read event.currentTarget.checked. Switch has no onCheckedChange prop.

Shared props

PropSupportedNotes
as / asChildNoSwitch owns its native input and visual control structure.
Style propsNoSwitch exposes semantic form and appearance props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the visual switch root.
refYesForwards to the native input.
Native HTML attributesYesNative input attributes, including checked/defaultChecked and descriptive ARIA attributes, are forwarded; Switch owns type, role, and aria-checked.

Accessibility

Switch renders a native input with role="switch". Space toggles the focused control; Enter does not. Give it a stable visible setting label, not On, Off, or a label that changes with the value. Add a description when the consequence needs explanation. When a change saves immediately, provide visible and announced pending, success, or failure feedback.

Content guidance

Name the setting, not its current state. Keep the label stable as the switch changes.

DoDon't
label="Email notifications"label={checked ? "On" : "Off"}