Toggle Group

A toggle group joins several two-state buttons into one control and tracks which of them are pressed. Users press one item at a time by default, and pressing another item releases the one before it. Unlike a radio group, a toggle group can be empty, because pressing the pressed item again releases it. The group is a single tab stop, and the arrow keys move focus between its items.

UsageCopy Anchor Link

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

export function ToggleGroupDefault() {
	return (
		<ToggleGroup aria-label="Stock level">
			<ToggleGroupItem value="in-stock">In stock</ToggleGroupItem>
			<ToggleGroupItem value="low-stock">Low stock</ToggleGroupItem>
			<ToggleGroupItem value="out-of-stock">Out of stock</ToggleGroupItem>
		</ToggleGroup>
	);
}

ExamplesCopy Anchor Link

MultipleCopy Anchor Link

Filters often work together, for example when users narrow a product list to several categories at once. With multiple, pressing an item no longer releases the others, so users press as many items as the task needs and release each one on its own.

Pressed by DefaultCopy Anchor Link

A view rarely starts from nothing, because most lists open with the filter that users apply most often. Through defaultValue, the matching items are pressed when the view appears, and users adjust the selection from there.

ControlledCopy Anchor Link

When other parts of the interface depend on the selection, the application holds it itself. The selection then follows value and onValueChange, so a saved view can restore the pressed items and a reset action can release all of them at once.

OutlineCopy Anchor Link

In a dense filter bar, items that stand out only once they are pressed are easy to overlook. Set to "outline", variant gives every item a visible boundary, so users recognize each option as something to press before they have pressed any of them.

SmallCopy Anchor Link

Above a table or inside a card header, a toggle group shares little space with the content it filters. With size set to "sm", every item takes less room, so the control stays secondary to the figures.

Default SizeCopy Anchor Link

Forms, dialogs and page headers call for a toggle group of regular scale, the same in every product. Items take the size "default" unless another one is set, and size set to "default" on the group states it for all of them at once.

LargeCopy Anchor Link

One choice can shape a whole screen, such as switching a dashboard between the stores of a region. Given the size "lg", every item gains weight, so users find that choice at once.

Custom SpacingCopy Anchor Link

Every layout has its own density, and a toggle group adapts to it. Through spacing, the gap between the items follows the spacing unit of the system, so a larger value separates the options more clearly and a smaller one keeps them close together.

Without SpacingCopy Anchor Link

Closely related options, such as the levels of detail of a report, read best as one control. Set to 0, spacing joins the items, so users perceive the group as a whole and each item as one of its positions.

Outline without SpacingCopy Anchor Link

The joined form gains clarity when each option keeps a boundary of its own. Combined with variant set to "outline", spacing set to 0 lets neighboring items share one border, so the group reads as a single segmented control in which every option stays distinct.

VerticalCopy Anchor Link

Long option names or a narrow sidebar leave no room for a row. With orientation set to "vertical", the items stack in a column, and users move between them with the up and down arrow keys.

With IconCopy Anchor Link

Options that users switch between many times a day become familiar at a glance. An icon helps them recognize each option before they read it, and the label keeps the meaning clear for users who meet the option for the first time.

DisabledCopy Anchor Link

While the data behind a view is still loading, its filters have nothing to act on. Marked as disabled, the toggle group ignores every press and drops out of the keyboard order, while the current selection stays visible and assistive technology receives the disabled state.

Disabled ItemCopy Anchor Link

Some options do not apply everywhere, for example a pickup service that a particular store does not offer. Set on a single item, disabled takes that option out of reach, and keyboard focus passes over it while users choose freely among the others.

InvalidCopy Anchor Link

A form can require a choice before users continue, for example the type of a price change. Through aria-invalid on its items, the group marks the choice as invalid, so users see where the form needs their attention before they submit it.

API ReferenceCopy Anchor Link

ToggleGroupCopy Anchor Link

ToggleGroupItemCopy Anchor Link