useSwitch

Hook that manages switch toggle state, checked/unchecked logic, and ARIA attributes.

Notifications

basic-demo

Usage#

import { useSwitch } from '@primereact/headless/switch';
 
const { rootProps, inputProps, controlProps, thumbProps } = useSwitch({
    defaultChecked: false
});
 
return (
    <div {...rootProps}>
        <input {...inputProps} />
        <div {...controlProps}>
            <span {...thumbProps} />
        </div>
    </div>
);

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

Features#

Returns spread-ready prop objects (rootProps, inputProps, controlProps, thumbProps)
Controlled and uncontrolled checked state
Hidden native checkbox with role="switch" for accessibility
Invalid and disabled state support with data attributes
Exposes onChange for custom toggle logic

Behavior#

Default Checked#

Use defaultChecked to set the initial checked state.

const sw = useSwitch({ defaultChecked: true });

Controlled#

Use checked and onCheckedChange for full programmatic control.

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

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

Disabled#

Set disabled to prevent interaction. inputProps sets disabled on the native input and all prop objects add data-disabled.

const sw = useSwitch({ disabled: true });

Invalid#

Set invalid to mark the switch as invalid. All prop objects add data-invalid and inputProps adds aria-invalid.

const sw = useSwitch({ invalid: true });

Custom Styling with Data Attributes#

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

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

API#

useSwitch#

Name	Type	Default
`checked`	`boolean`	—
When present, it specifies the input's checked state.
`defaultChecked`	`boolean`	—
The default value for the input when not controlled by `checked` and `onCheckedChange` .
`disabled`	`boolean`	`false`
Whether the switch is disabled.
`invalid`	`boolean`	`false`
When present, it specifies that the switch value is invalid.
`tabIndex`	`number`	—
Index of the element in tabbing order.
`ariaLabel`	`string`	—
Establishes a string value that labels the component.
`ariaLabelledby`	`string`	—
Establishes relationships between the component and label(s) where its value should be one or more element IDs.
`onFocus`	`FocusEventHandler<HTMLInputElement>`	—
Callback function that is called when the switch is focused.
`onBlur`	`FocusEventHandler<HTMLInputElement>`	—
Callback function that is called when the switch loses focus.
`onCheckedChange`	`(event: useSwitchChangeEvent) => void`	—
Callback fired when the switch's checked state changes.

Accessibility#

See Switch Primitive for WAI-ARIA compliance details and keyboard support.