Toggle Group

A set of segmented, two-state buttons that can be toggled on or off, perfect for configuration settings and rich text editors.

This component utilizes a React Context Provider to make composition incredibly easy. Instead of passing active states and onClick handlers to every single button, you simply wrap your <ToggleGroupItem> components inside the parent <ToggleGroup> and it handles all of the logic automatically.

Explore the different variations of the Toggle Group — each example shows a live preview with the exact code to copy.

Toggle Group

Single selection — exactly one item stays active at a time.

type"single": is the default and behaves like radio buttons.
value: is a string here; pair it with onValueChange, or use defaultValue to stay uncontrolled.

Active Color Theme

Installation

New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.

Install Toggle Group

npx shadcn@latest add @algorize-ui/toggle-group

components/custom/blocks/ToggleGroupBlock.tsx is written into your project. Copy any snippet from a Usage tab above and it runs.

Install dependencies

Nothing beyond the shared setup — Toggle Group needs only the cn helper and lucide-react, which the installation guide already put in place.

Examples

Outline

Usevariant"outline": to draw a border around the segment.

Ghost

Usevariant"ghost": for items that only paint when active — no pill container.

Segmented

A view switch: one highlight slides to the chosen item, which stays chosen when clicked again. The arrow keys move the choice.

Usevariant"segmented": for a pill track with a sliding highlight. It reads best with text labels and type="single".

Sizes

Usesize: to change the item height and padding across the whole group.

Multiple selection

Settype"multiple": for checkbox behaviour.
value: becomes a string array in this mode — passing a bare string selects nothing.

Disabled

Setdisabled: on the group to lock every item at once, rather than disabling them one by one.

Usage

Use the type prop on the parent <ToggleGroup> to determine if the user can select only one option ("single") or many options ("multiple").

Props Reference

Component	Prop	Type	Default	Description
`ToggleGroup`	`type`	`"single" \| "multiple"`	`"single"`	Determines the selection behavior. `"single"` acts like radio buttons, while `"multiple"` acts like checkboxes.
`ToggleGroup`	`value`	`string \| string[]`	`undefined`	The controlled value of the group. Pass a string for the `single` type, or an array of strings for the `multiple` type.
`ToggleGroup`	`defaultValue`	`string \| string[]`	`undefined`	The initial value if you are using the component in an uncontrolled manner.
`ToggleGroup`	`onValueChange`	`(value: string \| string[]) => void`	`undefined`	A callback fired whenever the active selection changes.
`ToggleGroup`	`variant`	`"default" \| "outline" \| "ghost" \| "segmented"`	`"default"`	The architectural style of the group. The `default` variant wraps the items in a styled pill container; `segmented` is a pill track whose highlight slides to the pressed item, keeps a single choice pressed, and moves it with the arrow keys.
`ToggleGroup`	`color`	`"primary" \| "indigo" \| "rose" \| "emerald" \| "zinc" \| string`	`"primary"`	The dynamic accent color applied to active items. `"primary"` follows your theme's `--primary` token; custom hex codes are fully supported.
`ToggleGroup`	`size`	`"sm" \| "md" \| "lg"`	`"md"`	Uniformly controls the height, padding, and text size of all child toggle items.
`ToggleGroup`	`disabled`	`boolean`	`false`	If true, completely disables all interaction for every item inside the group.
`ToggleGroupItem`	`value`	`string`	Required	The unique identifier for this specific toggle button. This is the value passed to `onValueChange`.
`ToggleGroupItem`	`disabled`	`boolean`	`false`	Disables this specific item, independently of the parent group's disabled state.