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

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="large" 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