Toggle and ToggleGroup
A button with an on and an off state, and a group of them that shares one value, for one choice or several.
A toggle is a button that stays pressed: bold on or off, notifications muted or not. A toggle group joins several of them into one value: one alignment out of three, or any combination of text styles. Use a toggle for a setting that takes effect at once; for a choice that is submitted with a form, use a checkbox, a switch or a radio group, which are form controls.
Notifications are on.
// apps/docs/examples/ui/toggle.tsx'use client';
import {useState} from 'react';import {BellIcon, BellOffIcon, BoldIcon} from 'lucide-react';
import {Toggle} from '@workspace/active-ui/components/primitives/toggle';
/** * A button with an on and an off state. Uncontrolled, it keeps its own * state; controlled, `pressed` and `onPressedChange` hand it to your * application. Its state is announced as `aria-pressed`. */export default function ToggleExample() { const [muted, setMuted] = useState(false); return ( <div className="flex flex-wrap items-center gap-4"> <Toggle aria-label="Bold"> <BoldIcon aria-hidden /> </Toggle> <Toggle variant="outline" pressed={muted} onPressedChange={setMuted}> {muted ? ( <BellOffIcon data-icon="inline-start" aria-hidden /> ) : ( <BellIcon data-icon="inline-start" aria-hidden /> )} Mute notifications </Toggle> <p className="text-muted-foreground text-sm" aria-live="polite"> Notifications are {muted ? 'muted' : 'on'}. </p> <Toggle disabled aria-label="Bold, not available"> <BoldIcon aria-hidden /> </Toggle> </div> );}Usage#
import {Toggle} from '@workspace/active-ui/components/primitives/toggle';import { ToggleGroup, ToggleGroupItem,} from '@workspace/active-ui/components/primitives/toggle-group';
<Toggle aria-label="Bold"> <BoldIcon aria-hidden /></Toggle>;
<ToggleGroup aria-label="Alignment" value={align} onValueChange={setAlign}> <ToggleGroupItem value="left">Left</ToggleGroupItem> <ToggleGroupItem value="right">Right</ToggleGroupItem></ToggleGroup>;A group of toggles#
Value: ["left"]
Value: ["bold"]
// apps/docs/examples/ui/toggle-group.tsx'use client';
import {useState} from 'react';import { AlignCenterIcon, AlignLeftIcon, AlignRightIcon, BoldIcon, ItalicIcon, UnderlineIcon,} from 'lucide-react';
import { ToggleGroup, ToggleGroupItem,} from '@workspace/active-ui/components/primitives/toggle-group';
/** * Toggles that share one value. By default one item at a time is pressed * (alignment); with `multiple` any number (text style). The value is always * an array of the `value`s of the pressed items. `spacing={0}` joins the * items into one outlined control. */export default function ToggleGroupExample() { const [align, setAlign] = useState<string[]>(['left']); const [style, setStyle] = useState<string[]>(['bold']); return ( <div className="flex flex-col items-start gap-6"> <div className="flex flex-col gap-2"> <ToggleGroup aria-label="Alignment" variant="outline" spacing={0} value={align} onValueChange={setAlign} > <ToggleGroupItem value="left" aria-label="Align left"> <AlignLeftIcon aria-hidden /> </ToggleGroupItem> <ToggleGroupItem value="center" aria-label="Align center"> <AlignCenterIcon aria-hidden /> </ToggleGroupItem> <ToggleGroupItem value="right" aria-label="Align right"> <AlignRightIcon aria-hidden /> </ToggleGroupItem> </ToggleGroup> <p className="text-muted-foreground text-sm"> Value: <code>{JSON.stringify(align)}</code> </p> </div> <div className="flex flex-col gap-2"> <ToggleGroup aria-label="Text style" multiple value={style} onValueChange={setStyle} > <ToggleGroupItem value="bold" aria-label="Bold"> <BoldIcon aria-hidden /> </ToggleGroupItem> <ToggleGroupItem value="italic" aria-label="Italic"> <ItalicIcon aria-hidden /> </ToggleGroupItem> <ToggleGroupItem value="underline" aria-label="Underline"> <UnderlineIcon aria-hidden /> </ToggleGroupItem> </ToggleGroup> <p className="text-muted-foreground text-sm"> Value: <code>{JSON.stringify(style)}</code> </p> </div> </div> );}The value is always an array of the
values of the pressed items, also when only one item can be pressed. Withoutmultiple, pressing an item releases the other; pressing the pressed item releases it, so the value can be empty. Refuse an empty value inonwhen your application needs one.Value Change variantandsizeon the group apply to every item.spacingsets the gap between the items in steps of the spacing scale (default2);0joins them into one control with shared borders, best withvariant="outline".orientation="vertical"stacks the items and makes the arrow keys follow.
Variants and sizes#
variant:default(no border, a muted fill when pressed) oroutline(a border).size:sm,defaultorlg, with the same heights as the buttons of those sizes.Mark an icon beside text with
data-oricon="inline- start" data-, as on a button.icon="inline- end"
What your application provides#
An accessible name for each icon-only toggle, and for the group.
The state when it is controlled:
pressedandonon a toggle,Pressed Change valueandonon a group.Value Change What the state changes on the page. A toggle only reports it.
Accessibility and keyboard#
A toggle is a
<button>witharia-;pressed SpaceandEnterswitch it.In a group, the arrow keys move the focus between the items (left and right, or up and down when vertical) and
Tableaves the group;loop(defaultFocus true) wraps from the last item to the first.A disabled toggle or group (
disabled) is skipped and cannot be switched.
API#
Toggle#
Import from @workspace/
Props marked Base UI are behaviour of the Base UI part this component is built on.
Props
- Type
boolean
Whether the toggle button is currently pressed. This is the controlled counterpart of default.
- Type
boolean- Default
false
Whether the toggle button is currently pressed. This is the uncontrolled counterpart of pressed.
- Type
boolean- Default
false
Whether the component should ignore user interaction.
- Type
"default""lg""sm"null- Default
'default'
The height and horizontal padding: sm, default or lg, the heights of the buttons of the same size.
- Type
string
A unique string that identifies the toggle when used inside a toggle group.
- Type
"default""outline"null- Default
'default'
The look: default has no border, outline a border and a light shadow. Pressed, both get the muted fill.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Events
Called by the component when something happens.
- Type
(pressed, eventDetails) => void
Callback fired when the pressed state is changed.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
ToggleGroup#
Import from @workspace/
Props marked Base UI are behaviour of the Base UI part this component is built on.
Props
- Type
readonly string[]
The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of default.
- Type
readonly string[]
The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of value.
- Type
boolean- Default
false
Whether the toggle group should ignore user interaction.
- Type
boolean- Default
true
Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
- Type
boolean- Default
false
When false only one item in the group can be pressed. If any item in the group becomes pressed, the others will become unpressed. When true multiple items can be pressed.
- Type
"horizontal""vertical"- Default
'horizontal'
The direction of the items, and of the arrow keys that move between them.
- Type
"default""lg""sm"null
The height and horizontal padding: sm, default or lg, the heights of the buttons of the same size.
- Type
number- Default
2
The gap between the items, in steps of the spacing scale. 0 joins the items into one control with shared borders.
- Type
"default""outline"null
The look: default has no border, outline a border and a light shadow. Pressed, both get the muted fill.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Events
Called by the component when something happens.
- Type
(groupValue, event Details) => void
Callback fired when the pressed states of the toggle group changes.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
ToggleGroupItem#
Import from @workspace/
Props marked Base UI are behaviour of the Base UI part this component is built on.
Props
- Type
boolean
Whether the toggle button is currently pressed. This is the controlled counterpart of default.
- Type
boolean- Default
false
Whether the toggle button is currently pressed. This is the uncontrolled counterpart of pressed.
- Type
boolean- Default
false
Whether the component should ignore user interaction.
- Type
"default""lg""sm"null- Default
'default'
The height and horizontal padding: sm, default or lg, the heights of the buttons of the same size.
- Type
string
A unique string that identifies the toggle when used inside a toggle group.
- Type
"default""outline"null- Default
'default'
The look: default has no border, outline a border and a light shadow. Pressed, both get the muted fill.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Events
Called by the component when something happens.
- Type
(pressed, eventDetails) => void
Callback fired when the pressed state is changed.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Other exports#
Functions, hooks and constants
(props?: (ConfigVariants<{ variant: { default: string; outline: string; }; size: { default: string; sm: string; lg: string; }; }> & ClassProp) | undefined) => stringThis page adapts the Toggle and Toggle Group documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.