useRadioButton

Hooks that manage radio button and radio button group state, checked logic, and ARIA attributes.

Standard

Express

Overnight

basic-demo

Usage#

import { useRadioButton } from '@primereact/headless/radiobutton';
import { useRadioButtonGroup } from '@primereact/headless/radiobuttongroup';
 
const group = useRadioButtonGroup({ defaultValue: 'a' });
const { rootProps, inputProps, boxProps, indicatorProps, state } = useRadioButton({
    value: 'a',
    checked: group.state.value === 'a',
    onCheckedChange: (e) => group.updateChange({ ...e, value: 'a' })
});
 
return (
    <div {...rootProps}>
        <input {...inputProps} className="sr-only" />
        <div {...boxProps}>{state.checked && <span {...indicatorProps} />}</div>
    </div>
);

useRadioButton manages checked state for a single option while useRadioButtonGroup manages the shared value — see Primitive for a component-based API.

Features#

Returns spread-ready prop objects (rootProps, inputProps, boxProps, indicatorProps)
Controlled and uncontrolled checked state
useRadioButtonGroup for managing a shared value across multiple radio buttons
Exposes onChange and updateChange for custom toggle logic

Behavior#

Default Checked#

Use defaultChecked to set the initial checked state of a standalone radio button.

const radio = useRadioButton({ defaultChecked: true });

Controlled#

Use checked and onCheckedChange for full programmatic control.

const [checked, setChecked] = React.useState(true);
const radio = useRadioButton({
    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 rootProps adds data-disabled.

const radio = useRadioButton({ disabled: true });

Read Only#

Set readOnly to prevent state changes while keeping the radio button focusable.

const radio = useRadioButton({ readOnly: true });

Radio Button Group#

Use useRadioButtonGroup to manage a shared value. Pass the group's updateChange method to individual radio buttons.

const group = useRadioButtonGroup({ defaultValue: 'a' });
 
const radioA = useRadioButton({
    value: 'a',
    checked: group.state.value === 'a',
    onCheckedChange: (e) => group.updateChange({ ...e, value: 'a' })
});

Controlled Group#

Use value and onValueChange on the group for full programmatic control.

const [value, setValue] = React.useState<unknown>('a');
const group = useRadioButtonGroup({
    value,
    onValueChange: (e) => setValue(e.value)
});

Custom Styling with Data Attributes#

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

[data-scope='radiobutton'][data-part='box'] {
    width: 1.125rem;
    height: 1.125rem;
    border: 1px solid #ccc;
    border-radius: 9999px;
}
 
[data-scope='radiobutton'][data-part='box'][data-checked] {
    background: var(--p-primary-color);
    border-color: var(--p-primary-color);
}
 
[data-scope='radiobutton'][data-part='indicator'][data-checked] {
    width: 0.625rem;
    height: 0.625rem;
    border-radius: 9999px;
    background: white;
}
 
[data-scope='radiobutton'][data-part='root'][data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
}

API#

useRadioButton#

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` .
`inputId`	`string`	—
Identifier of the underlying input element.
`value`	`unknown`	—
Value of the radio button.
`name`	`string`	—
The name attribute of the input, resolved from group context if available.
`disabled`	`boolean`	`false`
When present, it specifies that the element should be disabled.
`readOnly`	`boolean`	`false`
When present, it specifies that an input field is read-only.
`required`	`boolean`	`false`
When present, it specifies that the element is required.
`tabIndex`	`number`	—
Tab index for keyboard navigation.
`invalid`	`boolean`	`false`
When present, it specifies that the component should have invalid state style.
`ariaLabelledby`	`string`	—
Establishes relationships between the component and label(s) where its value should be one or more element IDs.
`ariaLabel`	`string`	—
Establishes a string value that labels the component.
`onFocus`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback function that is called when the radio button is focused.
`onBlur`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback function that is called when the radio button loses focus.
`onCheckedChange`	`(event: useRadioButtonChangeEvent) => void`	—
Callback fired when the radio button's checked state changes.

useRadioButtonGroup#

Name	Type	Default
`value`	`unknown`	—
Value of the radio button group.
`defaultValue`	`unknown`	—
The default value of the radio button group.
`onValueChange`	`(event: useRadioButtonGroupValueChangeEvent) => void`	—
Callback fired when the radio button group's value state changes.

Accessibility#

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