ToggleButton

An unstyled toggle button component with group selection support for single and multiple modes.

Build fully custom toggle buttons and button groups with complete control over layout and styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use ToggleButton with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with sub-components: Root, Indicator
Standalone toggle with boolean pressed state
Group selection with ToggleButtonGroup for single and multiple modes
Configurable allowEmpty to require at least one selection in a group

Usage#

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

<ToggleButton.Root>
    <ToggleButton.Indicator></ToggleButton.Indicator>
</ToggleButton.Root>
 
<ToggleButtonGroup>
    <ToggleButton.Root value="a">
        <ToggleButton.Indicator></ToggleButton.Indicator>
    </ToggleButton.Root>
    <ToggleButton.Root value="b">
        <ToggleButton.Indicator></ToggleButton.Indicator>
    </ToggleButton.Root>
</ToggleButtonGroup>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered element.

<ToggleButton.Root as="div"></ToggleButton.Root>
<ToggleButton.Indicator as="span"></ToggleButton.Indicator>

Default elements: Root=button, Indicator=span, ToggleButtonGroup=div.

Render Function Children#

Indicator accepts a render function as children, providing access to the component instance. The instance exposes togglebutton (parent instance with state.pressed).

<ToggleButton.Indicator>{({ togglebutton }: ToggleButtonIndicatorInstance) => (togglebutton?.state.pressed ? 'On' : 'Off')}</ToggleButton.Indicator>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

ToggleButtonRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToggleButtonRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToggleButtonRootInstance) => 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`	`ToggleButtonRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToggleButtonRootPassThrough>`	—
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: ToggleButtonRootInstance) => 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.
`pressed`	`boolean`	—
When present, it specifies that the ToggleButton should be pressed.
`defaultPressed`	`boolean`	—
The default pressed value when not controlled by `pressed` and `onPressedChange` .
`value`	`unknown`	—
Value of the ToggleButton.
`size`	`"small"` \| `"large"` \| `"normal"`	—
Defines the size of the ToggleButton.
`disabled`	`boolean`	`false`
When present, it specifies that the element should be disabled.
`invalid`	`boolean`	`false`
When present, it specifies that the component should have invalid state style.
`onPressedChange`	`(event: ToggleButtonRootChangeEvent) => void`	—
Callback fired when the ToggleButton's pressed state changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-pressed`	Present when pressed
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid

Defines passthrough(pt) options of ToggleButton component.

label	type	description
root	ToggleButtonRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
indicator	ToggleButtonRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the indicator's DOM element.

ToggleButtonIndicator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToggleButtonIndicatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToggleButtonIndicatorInstance) => 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`	`ToggleButtonIndicatorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToggleButtonIndicatorPassThrough>`	—
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: ToggleButtonIndicatorInstance) => 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.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-pressed`	Present when pressed
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid

Defines passthrough(pt) options of ToggleButtonIndicator component.

label	type	description
root	ToggleButtonIndicatorPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

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.
`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#

ToggleButton uses aria-pressed to indicate its toggle state and aria-disabled when disabled. Provide aria-label or visible text content to give each button an accessible name. ToggleButtonGroup uses role="group" and should have aria-label to describe the group purpose.

<ToggleButton.Root aria-label="Favorite">
    <ToggleButton.Indicator></ToggleButton.Indicator>
</ToggleButton.Root>
 
<ToggleButtonGroup aria-label="Text alignment">
    <ToggleButton.Root value="left" aria-label="Align left">
        <ToggleButton.Indicator></ToggleButton.Indicator>
    </ToggleButton.Root>
</ToggleButtonGroup>

Keyboard Support#

Key	Function
`Space`	Toggles the pressed state.
`Enter`	Toggles the pressed state.
`Tab`	Moves focus to the next element.