ToggleButtonGroup

An unstyled container that groups multiple toggle buttons with single or multiple selection.

Coordinate multiple ToggleButton controls under a shared value with single or multiple selection and complete control over layout and styling.

Features#

Manages a shared value across multiple ToggleButton.Root items
multiple for multi-selection, allowEmpty to permit an empty selection
Works with the compound ToggleButton API (Root, Indicator)

Usage#

import { ToggleButton } from 'primereact/togglebutton';
import { ToggleButtonGroup } from 'primereact/togglebuttongroup';

<ToggleButtonGroup allowEmpty={false} multiple={false}>
    <ToggleButton.Root value="left">
        <ToggleButton.Indicator>
            <i className="pi pi-align-left" />
        </ToggleButton.Indicator>
    </ToggleButton.Root>
    <ToggleButton.Root value="center">
        <ToggleButton.Indicator>
            <i className="pi pi-align-center" />
        </ToggleButton.Indicator>
    </ToggleButton.Root>
</ToggleButtonGroup>

API#

ToggleButtonGroup#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToggleButtonGroupInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToggleButtonGroupInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToggleButtonGroupInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToggleButtonGroupPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToggleButtonGroupInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`value`	`unknown`	—
Value of the ToggleButtonGroup.
`defaultValue`	`unknown`	—
The default value of the ToggleButtonGroup.
`multiple`	`boolean`	`false`
When present, it specifies that the ToggleButton group allows multiple selections.
`allowEmpty`	`boolean`	`true`
When present, it specifies that the ToggleButton group allows empty selection.
`size`	`"small"` \| `"large"` \| `"normal"`	—
Defines the size of the ToggleButton components.
`disabled`	`boolean`	`false`
When present, it specifies that the ToggleButton group should be disabled.
`invalid`	`boolean`	`false`
When present, it specifies that the ToggleButton group is invalid.
`fluid`	`boolean`	—
Spans 100% width of the container when enabled.
`onValueChange`	`(event: ToggleButtonGroupValueChangeEvent) => void`	—
Callback function that is called when the ToggleButton group value changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"togglebuttongroup"`
`data-part`	`"root"`
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-multiple`	Present when multiple selection active
`data-allow-empty`	Present when empty selection allowed

Accessibility#

ToggleButtonGroup uses role="group" and should have an aria-label describing the group's purpose. Each ToggleButton.Root uses aria-pressed to indicate its toggle state.

Keyboard Support#

Key	Function
`tab`	Moves focus to the next button.
`space`	Toggles the focused button.