Toggle

A two-state button that can be toggled on or off, used standalone or within a group.

Anatomy

Import and use the component:

1import { Toggle } from "@raystack/apsara";
2

3<Toggle aria-label="Bold">B</Toggle>

Use Toggle.Group to manage a set of toggles with shared state:

1<Toggle.Group defaultValue={["left"]}>
2  <Toggle value="left" aria-label="Align left">L</Toggle>
3  <Toggle value="center" aria-label="Align center">C</Toggle>
4  <Toggle value="right" aria-label="Align right">R</Toggle>
5</Toggle.Group>

API Reference

Root

A two-state button that can be toggled on or off.

Prop

Type

Group

Groups multiple toggle buttons and manages their shared pressed state.

Prop

Type

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

SlotElement
toggleThe toggle button itself
toggle-contentThe <span> wrapping the toggle's children
toggle-groupThe Toggle.Group container

Examples

Group

Use Toggle.Group for exclusive or multi-select toggle sets. By default, only one toggle can be pressed at a time.

1<Toggle.Group defaultValue={["center"]} aria-label="Text alignment">
2  <Toggle value="left" aria-label="Align left">
3    <TextAlignLeftIcon />
4  </Toggle>
5  <Toggle value="center" aria-label="Align center">
6    <TextAlignCenterIcon />
7  </Toggle>
8  <Toggle value="right" aria-label="Align right">
9    <TextAlignRightIcon />
10  </Toggle>
11</Toggle.Group>

Multiple Selection

Set multiple on the group to allow more than one toggle to be pressed simultaneously.

1<Toggle.Group multiple aria-label="Text formatting">
2  <Toggle value="bold" aria-label="Bold">
3    <FontBoldIcon />
4  </Toggle>
5  <Toggle value="italic" aria-label="Italic">
6    <FontItalicIcon />
7  </Toggle>
8  <Toggle value="underline" aria-label="Underline">
9    <UnderlineIcon />
10  </Toggle>
11</Toggle.Group>

Size

The toggle supports four sizes matching the icon button sizes.

1<Flex gap={9} align="center">
2  <Toggle size={1} aria-label="Bold">
3    <FontBoldIcon />
4  </Toggle>
5  <Toggle size={2} aria-label="Bold">
6    <FontBoldIcon />
7  </Toggle>
8  <Toggle size={3} aria-label="Bold">
9    <FontBoldIcon />
10  </Toggle>
11  <Toggle size={4} aria-label="Bold">
12    <FontBoldIcon />
13  </Toggle>
14</Flex>

Controlled

Control the pressed state programmatically.

1(function ControlledToggle() {
2  const [pressed, setPressed] = React.useState(false);
3  return (
4    <Toggle aria-label="Star" pressed={pressed} onPressedChange={setPressed}>
5      {pressed ? "★" : "☆"}
6    </Toggle>
7  );
8})

Disabled

Disable individual toggles or the entire group.

1<Toggle aria-label="Bold" disabled>
2  <b>B</b>
3</Toggle>

Accessibility

  • Uses native <button> element with aria-pressed for toggle state
  • Supports keyboard activation with Space and Enter keys
  • Toggle.Group renders with role="group" and supports arrow key navigation
  • Use aria-label on each toggle to provide an accessible name when using icon-only content