Toggle

When to UseCopy Anchor Link

• for a format that applies immediately and turns off the same way, such as bold or italic in an editor
• to mark one record, for example as a favorite
• as an outline Toggle with a label, for a filter that is on or off, like “Overdue”

When Not to UseCopy Anchor Link

• for an action that runs once on every click (use a Button)
• for a setting in a form (use a Switch or a Checkbox)
• for a set of Toggles that users move between with the arrow keys (use a Toggle Group)
• to choose one of a few options (use a Segmented Control)

AnatomyCopy Anchor Link

* A Toggle has a label, an icon, or both.

VariantsCopy Anchor Link

SizesCopy Anchor Link

A Toggle has the sm, default, and lg sizes of a Button and the same height at each, so the two line up in a toolbar. See Sizing for where to use each height.

A Toggle has no xs size and no icon sizes.

StatesCopy Anchor Link

A pressed Toggle has the same tint as a hovered one, so users can’t tell the state from the tint alone. Add a mark to a pressed Toggle as well.

See Elevation for the rule and Iconography for the two weights.

BehaviorCopy Anchor Link

By default, a Toggle is as wide as its content and at least as wide as it is tall. The label doesn’t wrap.

ContentCopy Anchor Link

aria-pressed communicates the state to assistive technology. The ARIA Authoring Practices Guide asks that the label of a toggle stay the same when its state changes.

AccessibilityCopy Anchor Link

Base UI’s Toggle renders a native button and sets aria-pressed on it.

InstallationCopy Anchor Link

npx shadcn@latest add @summit/toggle

UsageCopy Anchor Link

import { Toggle } from '@/components/ui/toggle';
import { TextBIcon } from '@phosphor-icons/react';

<Toggle aria-label="Bold">
    <TextBIcon />
</Toggle>;

Mark the Pressed StateCopy Anchor Link

To change the icon when the Toggle is pressed, pass a function to render. The function receives the props of the button and state.pressed.

import { StarIcon } from '@phosphor-icons/react';

<Toggle
    aria-label="Favorite"
    render={(props, state) => (
        <button type="button" {...props}>
            <StarIcon weight={state.pressed ? 'fill' : 'regular'} />
        </button>
    )}
/>;

With a LabelCopy Anchor Link

If the Toggle has a label, render the check only while the Toggle is pressed, and mark it with data-icon="inline-start".

import { CheckIcon } from '@phosphor-icons/react';

<Toggle
    variant="outline"
    render={(props, state) => (
        <button type="button" {...props}>
            {state.pressed && <CheckIcon data-icon="inline-start" />}
            Overdue
        </button>
    )}
/>;

API ReferenceCopy Anchor Link

Other props are passed to Base UI’s Toggle. See the Base UI Toggle documentation for pressed, defaultPressed, onPressedChange, and render.