Components

Switch

Toggles for turning a single setting on or off

About

Switch is built on React Aria and styled with Thumbprint v2 semantic tokens. Use it for a binary setting that takes effect immediately, such as enabling or disabling a feature or preference. When the change needs to be confirmed through a form submission, use a Checkbox instead.

Basic switch

The isChecked prop determines whether the switch is on, and onChange receives the new boolean value. Always pair a switch with an inline label that describes the feature being toggled.

function SwitchExample() {
    const [isChecked, setIsChecked] = React.useState(false);
    return (
        <Switch isChecked={isChecked} onChange={setIsChecked}>
            Email notifications
        </Switch>
    );
}

Sizes

The size prop controls the switch dimensions. large (the default) is the 52×32 control shared with iOS; small is a 36×20 web-only control for dense layouts.

function SwitchExample() {
    const [isChecked, setIsChecked] = React.useState(true);
    return (
        <Switch size="small" isChecked={isChecked} onChange={setIsChecked}>
            Email notifications
        </Switch>
    );
}

Disabled switches

The isDisabled prop visually and functionally disables the switch. It also visually disables the related label.

<React.Fragment>
    <Switch isDisabled onChange={() => {}}>
        Email notifications
    </Switch>
    <Switch isDisabled isChecked onChange={() => {}}>
        Push notifications
    </Switch>
</React.Fragment>

Switch with a description

The description prop renders secondary text beneath the label, and the label is emphasized. Use it for settings that benefit from extra context.

function SwitchExample() {
    const [isChecked, setIsChecked] = React.useState(false);
    return (
        <Switch
            isChecked={isChecked}
            onChange={setIsChecked}
            description="Get an email when a pro responds to your request."
        >
            Email notifications
        </Switch>
    );
}

Switch without a visible label

When the switch has no textual children (for example, a switch labeled by surrounding UI), provide an accessibilityLabel so assistive technologies can announce it.

function SwitchExample() {
    const [isChecked, setIsChecked] = React.useState(false);
    return (
        <Switch
            isChecked={isChecked}
            onChange={setIsChecked}
            accessibilityLabel="Email notifications"
        />
    );
}

Props

Switch

isChecked
Determines if the switch is on. Maps to React Aria's isSelected.

Type
boolean
defaultChecked
The default on state when the switch is uncontrolled. Maps to React Aria's defaultSelected.

Type
boolean
isDisabled
Disables the switch and the label. A disabled switch does not accept interaction and is rendered at reduced opacity.

Type
boolean
Default
false
isReadOnly
Makes the switch immutable while still focusable. Maps to React Aria's isReadOnly.

Type
boolean
Default
false
children
Text or elements that appear within the inline label. If children is not provided, the developer must use the accessibilityLabel prop to label the switch for assistive technologies.

Type
React.ReactNode
description
Secondary text rendered beneath the label. When provided, the label is emphasized. Maps to the [data-has-description] attribute.

Type
string
size
Sets the size of the switch. 'large' (the default) is the 52×32 control used on web and iOS; 'small' is the 36×20 web-only control. Maps to the [data-size] attribute.

Type
'small' | 'large'
Default
'large'
id
The id is added to the underlying switch input as an HTML attribute.

Type
string
name
Switches with the same name will be grouped together when sent to the server. The browser will only send the value of switches that are on.

Type
string
value
Determines the value that will be submitted if the switch is on. The default value is 'on'.

Type
string
onChange
Function that runs when the switch is toggled. It receives the new boolean value, matching React Aria's onChange signature.

Type
(isChecked: boolean) => void
onKeyDown
Function that is called when the user presses a key while focused on the switch. Maps to React Aria's onKeyDown.

Type
AriaSwitchProps['onKeyDown']
accessibilityLabel
Accessible label for the switch. Only needed if non-textual children are provided (e.g., images, emojis) or no children are provided. Maps to React Aria's aria-label.

Type
string
dataTestId
A selector hook into the React component for use in automated testing environments.

Type
string