A row of buttons that each stay pressed or not, any number at a time, such as the days an alarm repeats on, as the round weekday buttons of the iOS Clock app.

import { ToggleGroup } from "@plexui/ui/components/ToggleGroup";

A toggle group sets several on or off choices that belong together, where any number may be on, such as the days an alarm repeats on. Each item is a Button: solid in the group's color while pressed, soft secondary otherwise. For one choice out of several, use a SegmentedControl or a RadioGroup; for a single setting, a Switch or a Checkbox.

Examples

Overview

RepeatWed, Thu, and Fri

Text

Color and size

color

size

pill

Disabled

disabled

Notify me byAccount emails are always on. Add a phone number to get SMS.

API

ToggleGroup

Prop	Type	Default	Description
`value`	`string[]`	—	Controlled values of the pressed items
`defaultValue`	`string[]`	`[]`	Values of the items pressed at first (uncontrolled)
`onChange`	`(value: string[]) => void`	—	Called when an item is pressed or released, a newly pressed one last
`color`	`"primary" \| "secondary" \| "danger" \| "success" \| "info" \| "discovery" \| "caution" \| "warning"`	`"primary"`	Fill of a pressed item, a solid button in this color
`size`	`"3xs" \| "2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl"`	`"md"`	Size of the items, as the Button sizes
`pill`	`boolean`	`false`	Fully rounded items; with uniform, circles
`uniform`	`boolean`	`false`	Items as wide as they are tall, for a letter or an icon
`block`	`boolean`	`false`	Fills the width of its container, the items spread across it
`disabled`	`boolean`	`false`	Disables every item
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Reading direction of the items, which the arrow keys follow
`aria-label`	`string`	—	Name of the group, when no visible label names it
`aria-labelledby`	`string`	—	The id of the visible label of the group
`id`	`string`	—	The id of the group
`className`	`string`	—	CSS classes applied to the group

ToggleGroup.Item

Prop	Type	Default	Description
`value`	`string`	—	Value of the item, in the group's value while it is pressed
`disabled`	`boolean`	`false`	Disables the item
`aria-label`	`string`	—	Name of the item, when its content does not say it in full, such as a weekday's letter
`onClick`	`(event: MouseEvent) => void`	—	Called on a click before the item is pressed or released; event.preventDefault() keeps it as it is
`className`	`string`	—	CSS classes applied to the item
`children`	`ReactNode`	—	Content of the item: a label, a letter or an icon

The group is a toolbar with one Tab stop. Tab enters it on the first pressed item, else on the item focused last, else on the first, and the arrow keys move between items in the reading direction of dir, looping at the ends. Space and Enter press or release the focused item. Each item is a button with aria-pressed.

Styling

ToggleGroup reads these component tokens. Override them at any scope to restyle it; the items read the Button tokens:

--toggle-group-gap: space between items without block (default 8px)
--toggle-group-disabled-opacity: opacity of a disabled item, pressed or not (default 0.5)
--toggle-group-round-size, --toggle-group-round-font-size: the circle of a pill uniform item and its letter at 767px and below with touch.css (35px, 17px, the weekday buttons of the iOS Clock app)

Toggle Group