useToggleButton

Hooks that manage toggle button pressed state and group value selection with single or multiple modes.

basic-demo

Usage#

import { useToggleButton } from '@primereact/headless/togglebutton';
import { useToggleButtonGroup } from '@primereact/headless/togglebuttongroup';
 
const toggle = useToggleButton();
 
return (
    <button {...toggle.getRootProps()}>
        <span {...toggle.getIndicatorProps()}></span>
    </button>
);

useToggleButton manages a boolean pressed state and returns prop getter functions for root and indicator elements. useToggleButtonGroup coordinates multiple toggle buttons with single or multiple selection — see Primitive for a component-based API.

Features#

Prop getter functions getRootProps and getIndicatorProps that accept resolved disabled and invalid state
Controlled and uncontrolled pressed state via pressed / defaultPressed
Group hook with single and multiple selection modes via useToggleButtonGroup
Group methods isPressed and updateChange for coordinating child buttons

Behavior#

Default#

By default, a toggle button starts unpressed and toggles on click.

const toggle = useToggleButton();
 
toggle.state.pressed; // false initially

Controlled#

Pass pressed and onPressedChange to control the state externally.

const [pressed, setPressed] = useState(false);
const toggle = useToggleButton({
    pressed,
    onPressedChange: (e) => setPressed(e.pressed)
});

Disabled#

Pass true as the first argument to getRootProps to disable the button. The returned props include disabled, aria-disabled, and data-disabled.

const rootProps = toggle.getRootProps(true, false);

Group#

Use useToggleButtonGroup to manage a group of toggle buttons. Each child button derives its pressed state from the group via isPressed and reports changes via updateChange.

const group = useToggleButtonGroup({ allowEmpty: false });
 
const btn = useToggleButton({
    pressed: group.isPressed(group.state.value, 'bold'),
    onPressedChange: (e) => group.updateChange({ ...e, value: 'bold' })
});

Multiple Selection#

Set multiple on the group hook to allow more than one button to be pressed.

const group = useToggleButtonGroup({ multiple: true });

Allow Empty#

By default, allowEmpty is true, allowing all buttons to be unpressed. Set it to false to require at least one selection.

const group = useToggleButtonGroup({ allowEmpty: false });

Using `state` for Custom UI#

The hooks expose reactive state for custom rendering.

const toggle = useToggleButton();
toggle.state.pressed; // boolean
 
const group = useToggleButtonGroup({ multiple: true });
group.state.value; // unknown[]

Custom Styling with Data Attributes#

The prop getters include data attributes for styling.

button[data-pressed] {
    background-color: var(--p-primary-color);
    color: var(--p-primary-contrast-color);
}
 
button[data-disabled] {
    pointer-events: none;
    opacity: 0.6;
}
 
[data-scope='togglebuttongroup'][data-multiple] {
    /* styles for multi-select group */
}

API#