useToggleSwitch

Usage#

import { useToggleSwitch } from '@primereact/headless/toggleswitch';

const { rootProps, inputProps, controlProps, thumbProps } = useToggleSwitch({
    defaultChecked: false
});
 
<div {...rootProps}>
    <input {...inputProps} />
    <div {...controlProps}>
        <span {...thumbProps} />
    </div>
</div>;

useToggleSwitch manages boolean toggle state with a hidden native checkbox using role="switch". See Primitive for a component-based API.

Features#

• Composable parts — spreads props onto root, input, control, and thumb elements so the visual track and thumb are fully yours
• Switch semantics — hidden native checkbox with role="switch" preserves screen reader and keyboard behavior
• Controlled or uncontrolled — drive via checked/onCheckedChange or let the hook manage state from defaultChecked
• Validation flags — invalid and disabled emit aria-invalid, data-invalid, and data-disabled across the parts
• Animation-ready — data-checked on control and thumb lets you transition the track color and thumb position via CSS

Working with callbacks#

Controlled toggle switch#

Pass checked and onCheckedChange to own the state externally — needed for settings pages, async toggles, or validation flows.

const [checked, setChecked] = React.useState(false);
 
useToggleSwitch({
    checked,
    onCheckedChange: (e) => setChecked(e.checked)
});

The callback receives { originalEvent, checked } where checked is the new boolean.

Async confirmation before commit#

Intercept onCheckedChange to run a confirmation or network call before applying the new state.

const [checked, setChecked] = React.useState(false);
 
useToggleSwitch({
    checked,
    onCheckedChange: async (e) => {
        if (await confirmChange(e.checked)) setChecked(e.checked);
    }
});

Invalid state tied to form validation#

Flip invalid from your form state so CSS can react via data-invalid.

useToggleSwitch({
    invalid: formState.errors.notifications != null
});

Styling with data attributes#

Every prop object includes data-scope="toggleswitch" and a data-part attribute. State-dependent attributes are added automatically.

[data-scope='toggleswitch'][data-part='control'] {
    width: 2.5rem;
    height: 1.5rem;
    border-radius: 9999px;
    background: #ccc;
    transition: background 200ms;
}
 
[data-scope='toggleswitch'][data-part='control'][data-checked] {
    background: var(--p-primary-color);
}
 
[data-scope='toggleswitch'][data-part='thumb'] {
    width: 1rem;
    height: 1rem;
    border-radius: 9999px;
    background: white;
    transition: transform 200ms;
}
 
[data-scope='toggleswitch'][data-part='thumb'][data-checked] {
    transform: translateX(1rem);
}
 
[data-scope='toggleswitch'][data-part='root'][data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
}

API#

useToggleSwitch#

Accessibility#

Space toggles the on/off state while focused, matching native checkbox keyboard behavior. See Primitive for full WAI-ARIA compliance details.