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.
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.
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.
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.
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.
import { Switch } from "@smoothie-framework/whisk-react";
<Switch
defaultChecked
readOnly
label="Automatic backups"
description="Managed by your organization."
/>Props
Component props
Shared props
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.