Skip to content
comp0

comp0

Actions

Toggle Button

A button that stays on or off after a press.

When to use it: Use one for an independent setting or a group for small formatting choices.

On this page
  1. Example
  2. Anatomy
  3. Step by step
  4. Keyboard
  5. Forms and accessibility
  6. API reference

Example

Loading example…
Toggle Button.tsxtsx
import { ToggleButton, ToggleButtonGroup } from "@comp0/react";

export function Example() {
  return (
    <ToggleButtonGroup
      type="multiple"
      defaultValue={["bold"]}
      aria-label="Text style"
      className="inline-flex divide-x divide-zinc-950/10 overflow-hidden rounded border border-zinc-950/10 [&>button]:px-3 [&>button]:py-2.5 [&>button]:text-base [&>button]:text-zinc-950 [&>button]:outline-teal-600 [&>button]:focus-visible:outline-2 [&>button[data-selected]]:bg-teal-100 [&>button[data-selected]]:text-teal-950 sm:[&>button]:py-2 sm:[&>button]:text-sm dark:divide-white/10 dark:border-white/10 dark:[&>button]:text-zinc-50 dark:[&>button]:outline-teal-400 dark:[&>button[data-selected]]:bg-teal-950 dark:[&>button[data-selected]]:text-teal-50"
    >
      <ToggleButton value="bold">Bold</ToggleButton>
      <ToggleButton value="italic">Italic</ToggleButton>
      <ToggleButton value="underline">Underline</ToggleButton>
    </ToggleButtonGroup>
  );
}

Anatomy

Dashed frames are invisible state providers; shaded shapes own real DOM. Numbered pins match the list below.

A wireframe sketch of the assembled component. Each numbered marker matches a part in the list that follows.

  1. ToggleButtonGroupOptional

    Optional group; it announces the relationship and manages selection once type, value, defaultValue, or onChange is set. Owns a DOM element.

  2. ToggleButton

    Native button that owns the press target. Owns a DOM element.

Step by step

  1. 1

    Add the main part

    Start with one ToggleButton.

  2. 2

    Add the supporting parts

    Wrap related toggles in ToggleButtonGroup; give each button a value when the group should manage the selection.

  3. 3

    Make the behavior clear

    Pass type="single" or type="multiple" with value/defaultValue and onChange on the group, or keep defaultSelected per button when the group only organizes them.

    Exampletsx
    <ToggleButtonGroup type="multiple" defaultValue={["bold"]} aria-label="Text style">
  <ToggleButton value="bold">Bold</ToggleButton>
</ToggleButtonGroup>;

Keyboard

↵
Toggles the button.
Space
Toggles the button.

Forms and accessibility

Toggle buttons do not create native form values.

Accessibility checklist

  • Give icon-only toggles an aria-label.
  • Make the selected state visible, not only color.
  • Explain what on and off mean when it is not obvious.

API reference

Importtsx
import { ToggleButton, ToggleButtonGroup } from "@comp0/react";

ToggleButtonGroup

OptionalDOM element

Optional group; it announces the relationship and manages selection once type, value, defaultValue, or onChange is set.

PropTypeDescription
aria-labelstringNames the group for assistive technology.
orientation"horizontal" | "vertical"Direction exposed through data-orientation for styling.
type"single" | "multiple"Whether the group keeps one value or many.
valuestring | string[]Controlled selection: a string for single, a string[] for multiple.
defaultValuestring | string[]Initial selection: a string for single, a string[] for multiple.
onChange(value: string | string[]) => voidReceives the next selection; "" when a single group empties.

ToggleButton

DOM element

Native button that owns the press target.

PropTypeDescription
valuestringIdentifies the button inside a selection-managing group.
selectedbooleanControlled on state when standalone.
defaultSelectedbooleanInitial on state when standalone.
onChange(selected: boolean) => voidReceives the next on state.
disabledbooleanDisables the toggle.
commandstringInvoker command and target id, forwarded to the native button.
commandforstringInvoker command and target id, forwarded to the native button.
pendingbooleanDisables the button and sets aria-busy while work is in flight.

Style hooks

Attributes that appear while a state is true. Target them with Tailwind data variants such as data-open:bg-zinc-100, or with any CSS selector.

ToggleButton

Style hookMeaning
[data-selected]The button is on.
[data-disabled]It cannot change.

Keep exploring