RadioButton

An unstyled, accessible radio button component with compound composition and group support.

Build fully custom radio button controls with complete control over layout and styling.

Standard

Express

Overnight

basic-demo

Pre-styled Versions

Choose a pre-styled library to use RadioButton 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 three sub-components: Root, Box, Indicator
RadioButtonGroup for managing a shared value across multiple radio buttons
Conditional indicator rendering with match prop

Usage#

import { RadioButton } from 'primereact/radiobutton';
import { RadioButtonGroup } from 'primereact/radiobuttongroup';

<RadioButtonGroup>
    <RadioButton.Root value="a">
        <RadioButton.Box>
            <RadioButton.Indicator />
        </RadioButton.Box>
    </RadioButton.Root>
    <RadioButton.Root value="b">
        <RadioButton.Box>
            <RadioButton.Indicator />
        </RadioButton.Box>
    </RadioButton.Root>
</RadioButtonGroup>

Behavior#

Polymorphic Rendering#

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

<RadioButton.Root as="label">
    <RadioButton.Box as="span">
        <RadioButton.Indicator as="div" />
    </RadioButton.Box>
</RadioButton.Root>

Default elements: Root=div, Box=div, Indicator=span.

Render Function Children#

RadioButton.Box and RadioButton.Indicator accept a render function as children, providing access to the component instance.

<RadioButton.Box>{(instance) => <span>{instance.radiobutton?.state.checked ? '●' : '○'}</span>}</RadioButton.Box>

Pass Through#

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

🍓 Strawberry

🍌 Banana

🍉 Watermelon

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

API#

RadioButtonRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RadioButtonRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RadioButtonRootInstance) => 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`	`RadioButtonRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RadioButtonRootPassThrough>`	—
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: RadioButtonRootInstance) => 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.
`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` .
`tabIndex`	`number`	—
Tab index for keyboard navigation.
`value`	`unknown`	—
Value of the radio button.
`name`	`string`	—
The name of the radio button.
`size`	`"small"` \| `"large"` \| `"normal"`	—
Defines the size of the radio button.
`variant`	`"outlined"` \| `"filled"`	—
Specifies the input variant of the component.
`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.
`invalid`	`boolean`	`false`
When present, it specifies that the component should have invalid state style.
`inputId`	`string`	—
Identifier of the underlying input element.
`inputStyle`	`CSSProperties`	—
Inline style of the input field.
`inputClassName`	`string`	—
Style class of the input field.
`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`	`(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: RadioButtonRootChangeEvent) => void`	—
Callback fired when the radio button's checked state changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"radiobutton"`
`data-part`	`"root"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled

Defines passthrough(pt) options of RadioButton component.

label	type	description
root	RadioButtonRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
input	RadioButtonRootPassThroughType<InputHTMLAttributes<HTMLInputElement>>	Used to pass attributes to the input's DOM element.
box	RadioButtonRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the box's DOM element.
indicator	RadioButtonRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the indicator's DOM element.

RadioButtonBox#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RadioButtonBoxInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RadioButtonBoxInstance) => 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`	`RadioButtonBoxInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RadioButtonBoxPassThrough>`	—
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: RadioButtonBoxInstance) => 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-scope`	`"radiobutton"`
`data-part`	`"box"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled

Defines passthrough(pt) options of RadioButtonBox component.

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

RadioButtonIndicator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RadioButtonIndicatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RadioButtonIndicatorInstance) => 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`	`RadioButtonIndicatorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RadioButtonIndicatorPassThrough>`	—
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: RadioButtonIndicatorInstance) => 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.
`match`	`"checked"` \| `"unchecked"`	—
Determines the visibility of the indicator based on the state of the radio button. Valid values are: - "checked": Indicator is visible when the radio button is checked. - "unchecked": Indicator is visible when the radio button is unchecked.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"radiobutton"`
`data-part`	`"indicator"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled

Defines passthrough(pt) options of RadioButtonIndicator component.

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

RadioButtonGroup#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RadioButtonGroupInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RadioButtonGroupInstance) => 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`	`RadioButtonGroupInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RadioButtonGroupPassThrough>`	—
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: RadioButtonGroupInstance) => 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 radio button group.
`defaultValue`	`unknown`	—
The default value of the radio button group.
`name`	`string`	—
The name of the radio buttons.
`disabled`	`boolean`	`false`
When present, it specifies that the radio button group should be disabled.
`invalid`	`boolean`	`false`
When present, it specifies that the radio button group is invalid.
`onValueChange`	`(event: RadioButtonGroupValueChangeEvent) => void`	—
Callback fired when the radio button group's value state changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"radiobuttongroup"`
`data-part`	`"root"`

Defines passthrough(pt) options of RadioButtonGroup component.

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

Accessibility#

RadioButton component uses a hidden native radio button element internally that is only visible to screen readers. Value to describe the component can either be provided via label tag combined with inputId prop or using ariaLabelledby, ariaLabel props.

<label htmlFor="rb1">One</label>
<RadioButton.Root inputId="rb1">
    <RadioButton.Box>
        <RadioButton.Indicator />
    </RadioButton.Box>
</RadioButton.Root>
 
<span id="rb2">Two</span>
<RadioButton.Root ariaLabelledby="rb2">
    <RadioButton.Box>
        <RadioButton.Indicator />
    </RadioButton.Box>
</RadioButton.Root>
 
<RadioButton.Root ariaLabel="Three">
    <RadioButton.Box>
        <RadioButton.Indicator />
    </RadioButton.Box>
</RadioButton.Root>

Keyboard Support#

Key	Function
`tab`	Moves focus to the selected radio button in a group, or first one.
`space`	Selects the focused radio button.
`arrow`	In a named radio group, moves focus between options and updates choice.