Toggle Group

A set of toggles that make up one setting, spaced apart or joined into one control.

Repeat on

import { FieldLabel } from "@/components/ui/field";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

const days = [
  { value: "mon", label: "Monday" },
  { value: "tue", label: "Tuesday" },
  { value: "wed", label: "Wednesday" },
  { value: "thu", label: "Thursday" },
  { value: "fri", label: "Friday" },
  { value: "sat", label: "Saturday" },
  { value: "sun", label: "Sunday" },
];

export default function ToggleGroupMultiple() {
  return (
    <div className="flex flex-col gap-2">
      <FieldLabel id="repeat-on-label">Repeat on</FieldLabel>
      <ToggleGroup
        multiple
        spacing={1}
        defaultValue={["mon", "wed", "fri"]}
        aria-labelledby="repeat-on-label"
      >
        {days.map((day) => (
          <ToggleGroupItem key={day.value} value={day.value} aria-label={day.label}>
            {day.label[0]}
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
    </div>
  );
}

Installation

Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
Add toggle-group
pnpm dlx shadcn@latest add @jarvis/toggle-group

Usage

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export function NotifyBy() {
  return (
    <ToggleGroup multiple defaultValue={["email"]} aria-label="Notify me by">
      <ToggleGroupItem value="email">Email</ToggleGroupItem>
      <ToggleGroupItem value="push">Push</ToggleGroupItem>
      <ToggleGroupItem value="sms">SMS</ToggleGroupItem>
    </ToggleGroup>
  );
}

multiple lets any number of items be pressed. The value is always an array. Give the group an aria-label or aria-labelledby, and give icon-only items their own labels.

When exactly one option must be selected, use a Segmented Control. Inside a Toolbar, use ToolbarToggleGroup.

Examples

Single

Without multiple, only one item can be pressed at a time.

Was this helpful?

import { ThumbsDownIcon, ThumbsUpIcon } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupSingle() {
  return (
    <div className="flex items-center gap-3">
      <span id="helpful-label" className="text-sm text-muted-foreground">
        Was this helpful?
      </span>
      <ToggleGroup aria-labelledby="helpful-label">
        <ToggleGroupItem value="yes" aria-label="Yes">
          <ThumbsUpIcon />
        </ToggleGroupItem>
        <ToggleGroupItem value="no" aria-label="No">
          <ThumbsDownIcon />
        </ToggleGroupItem>
      </ToggleGroup>
    </div>
  );
}

Joined

Set spacing={0} to join the items into one control.

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupJoined() {
  return (
    <ToggleGroup
      multiple
      spacing={0}
      size="sm"
      defaultValue={["warn", "error"]}
      aria-label="Log levels"
    >
      <ToggleGroupItem value="debug">Debug</ToggleGroupItem>
      <ToggleGroupItem value="info">Info</ToggleGroupItem>
      <ToggleGroupItem value="warn">Warn</ToggleGroupItem>
      <ToggleGroupItem value="error">Error</ToggleGroupItem>
    </ToggleGroup>
  );
}

Give a Field or the group a name, and each pressed item's value submits under it, so formData.getAll(name) returns them all, and Form's onFormSubmit gets them as an array. Pass form with a form's id when the group sits outside it. With required, the form won't submit until an item is pressed, which fails as valueMissing. A form reset brings back defaultValue. Inside a Field, a FieldLabel names the group, and the group reads out the field's FieldDescription and FieldError.

import { Button } from "@/components/ui/button";
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Form } from "@/components/ui/form";
import { toast } from "@/components/ui/toast";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

const days = [
  { value: "mon", label: "Monday" },
  { value: "tue", label: "Tuesday" },
  { value: "wed", label: "Wednesday" },
  { value: "thu", label: "Thursday" },
  { value: "fri", label: "Friday" },
];

export default function ToggleGroupForm() {
  return (
    <Form
      className="max-w-sm"
      onFormSubmit={(values) =>
        toast.add({
          title: "Schedule saved",
          description: `Office days: ${(values.days as string[]).join(", ")}.`,
        })
      }
    >
      <Field name="days">
        <FieldLabel>Office days</FieldLabel>
        <ToggleGroup multiple spacing={1} required>
          {days.map((day) => (
            <ToggleGroupItem key={day.value} value={day.value} aria-label={day.label}>
              {day.label.slice(0, 2)}
            </ToggleGroupItem>
          ))}
        </ToggleGroup>
        <FieldDescription>The days you'll be in this week.</FieldDescription>
        <FieldError match="valueMissing">Choose at least one day.</FieldError>
      </Field>
      <Button type="submit" variant="primary" className="self-start">
        Save schedule
      </Button>
    </Form>
  );
}

Props

size on ToggleGroup applies to every item.

Part	Extends
ToggleGroup	Base UI's ToggleGroup
ToggleGroupItem	Base UI's Toggle

The tables leave out className, style and render. Parts built on Base UI take them as its styling and composition guides describe.

ToggleGroup

Prop	Type	Default
`value` 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 `defaultValue`.	`readonly string[]`	—
`defaultValue` 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`.	`readonly string[]`	—
`onValueChange` Callback fired when the pressed states of the toggle group changes.	`((groupValue: string[], eventDetails: ToggleGroup.ChangeEventDetails) => void)`	—
`disabled` Whether the toggle group should ignore user interaction.	`boolean`	`false`
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`
`loopFocus` Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.	`boolean`	`true`
`multiple` 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.	`boolean`	`false`
`size`	`"default" \| "lg" \| "sm"`	—
`spacing`	`number`	`2`
`name` Submits each pressed item's value with a form under this name.	`string`	—
`form` The `id` of the form to submit the value with, when the group isn't inside it.	`string`	—
`required` Whether a form can't be submitted until at least one item is pressed.	`boolean`	`false`

ToggleGroupItem

Prop	Type	Default
`pressed` Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`.	`boolean`	—
`defaultPressed` Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`.	`boolean`	`false`
`disabled` Whether the component should ignore user interaction.	`boolean`	`false`
`onPressedChange` Callback fired when the pressed state is changed.	`((pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void)`	—
`value` A unique string that identifies the toggle when used inside a toggle group.	`string`	—
`nativeButton` Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).	`boolean`	`true`
`size`	`"default" \| "lg" \| "sm"`	`"default"`