Toggle Group

Collect related pressed-state choices into a single group.

View component source ↗

Preview

Example

A minimal example to get started.

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/toggle-group.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

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

export default function Example() {
  return (
    <ToggleGroup defaultValue={["left"]} aria-label="Text alignment">
      <ToggleGroupItem value="left" aria-label="Align left">
        Left
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        Center
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        Right
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

ToggleGroup

ToggleGroup properties
Prop	Type	Default	Description
`value`	readonly string[] \| undefined readonly string[] \| undefined	`—`	The open state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of `defaultValue`.
`defaultValue`	readonly string[] \| undefined readonly string[] \| undefined	`—`	The open state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of `value`.
`onValueChange`	((groupValue: string[], eventDetails: ToggleGroupPrimitive.ChangeEventDetails) => void) \| … ((groupValue: string[], eventDetails: ToggleGroupPrimitive.ChangeEventDetails) => void) \| undefined	`—`	Callback fired when the pressed states of the toggle group changes.
`disabled`	boolean \| undefined boolean \| undefined	`false`	Whether the toggle group should ignore user interaction.
`orientation`	"horizontal" \| "vertical" \| undefined "horizontal" \| "vertical" \| undefined	`"horizontal"`	Layout axis used by the component.
`loopFocus`	boolean \| undefined boolean \| undefined	`true`	Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
`multiple`	boolean \| undefined boolean \| undefined	`false`	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.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: ToggleGroupState) => string \| undefined) \| undefined string \| ((state: ToggleGroupState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ToggleGroupState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	React.CSSProperties \| ((state: ToggleGroupState) => React.CSSProperties \| undefined) \| und… React.CSSProperties \| ((state: ToggleGroupState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`variant`	"default" \| "outline" \| null \| undefined "default" \| "outline" \| null \| undefined	`—`	Visual treatment of the component.
`size`	"default" \| "sm" \| "lg" \| null \| undefined "default" \| "sm" \| "lg" \| null \| undefined	`—`	Visual size of the component.
`spacing`	number \| undefined number \| undefined	`2`	Configures spacing; see the accepted type.

ToggleGroupItem

ToggleGroupItem properties
Prop	Type	Default	Description
`pressed`	boolean \| undefined boolean \| undefined	`—`	Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`.
`defaultPressed`	boolean \| undefined boolean \| undefined	`false`	Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`.
`disabled`	boolean \| undefined boolean \| undefined	`false`	Whether the component should ignore user interaction.
`onPressedChange`	((pressed: boolean, eventDetails: TogglePrimitive.ChangeEventDetails) => void) \| undefined ((pressed: boolean, eventDetails: TogglePrimitive.ChangeEventDetails) => void) \| undefined	`—`	Callback fired when the pressed state is changed.
`value`	string \| undefined string \| undefined	`—`	A unique string that identifies the toggle when used inside a toggle group.
`nativeButton`	boolean \| undefined boolean \| undefined	`true`	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>`).
`ref`	React.Ref<HTMLButtonElement> \| undefined React.Ref<HTMLButtonElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLButtonElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLButtonElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLButtonElement, MouseEvent>>) => void) \| undefine… ((event: BaseUIEvent<React.MouseEvent<HTMLButtonElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`name`	string \| undefined string \| undefined	`—`	Field name used in form data.
`type`	"button" \| "submit" \| "reset" \| undefined "button" \| "submit" \| "reset" \| undefined	`—`	The native input or button behavior.
`className`	string \| ((state: ToggleState) => string \| undefined) \| undefined string \| ((state: ToggleState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ToggleState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	React.CSSProperties \| ((state: ToggleState) => React.CSSProperties \| undefined) \| undefine… React.CSSProperties \| ((state: ToggleState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`variant`	"default" \| "outline" \| null \| undefined "default" \| "outline" \| null \| undefined	`"default"`	Visual treatment of the component.
`size`	"default" \| "sm" \| "lg" \| null \| undefined "default" \| "sm" \| "lg" \| null \| undefined	`"default"`	Visual size of the component.

Usage notes

Give every item a distinct value and label. Choose whether one or multiple options may be active for your use case.