Radio group components

Powerful and customizable React radio group components built for modern applications and websites. These radio groups are built using React Aria and styled with Tailwind CSS.

Icon simple

Get the code

Installation

You can add this radio groups component using our CLI or manually:

npx untitledui@latest add radio-groups

Icon card

Get the code

Avatar

Get the code

Payment icon

Get the code

Radio button

Get the code

Checkbox

Get the code

API reference

RadioGroupAvatar

Import RadioGroupAvatar from @/components/base/radio-groups/radio-group-avatar. Renders React Aria’s RadioGroup — all of its props are supported.

RadioGroupAvatar props
PropTypeDefaultDescription
items* (required)AvatarItemType[]—The people to choose between. Each renders as a selectable card with an avatar, name, username and job title.
size
"sm""md"
"sm"Scales the avatar, label text and selection checkbox in every card.
Props from React Aria (26)
RadioGroupAvatar inherited props
PropTypeDefaultDescription
onBlur((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element loses focus.
onFocus((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element receives focus.
onFocusChange((isFocused: boolean) => void)—Handler that is called when the element's focus status changes.
formstring—The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document.
namestring—The name of the input element, used when submitting an HTML form.
defaultValuestring | null—The default value (uncontrolled).
idstring—The element's unique identifier.
isDisabledboolean—Whether the input is disabled.
isInvalidboolean—Whether the input value is invalid.
isReadOnlyboolean—Whether the input can be selected but not changed by the user.
isRequiredboolean—Whether user input is required on the input before form submission.
onChange((value: string) => void)—Handler that is called when the value changes.
orientation
"horizontal""vertical"
"vertical"The axis the Radio Button(s) should align with.
validate((value: string) => ValidationError | true | null | undefined)—A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior
"native""aria"
"native"Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valuestring | null—The current value (controlled).
styleStyleOrFunction<RadioGroupRenderProps>—The inline style for the element. A function may be provided to compute the style based on component state.
childrenChildrenOrFunction<RadioGroupRenderProps>—The children of the component. A function may be provided to alter the children based on component state.
slotstring | null—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
classNameClassNameOrFunction<RadioGroupRenderProps>—The CSS className for the element. A function may be provided to compute the class based on component state.
renderDOMRenderFunction<"div", RadioGroupRenderProps>—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements:
  • You must render the expected element type (e.g. if <button> is expected, you cannot render an <a>).
  • Only a single root DOM element can be rendered (no fragments).
  • You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-errormessagestring—Identifies the element that provides an error message for the object.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

RadioGroupCheckbox

Import RadioGroupCheckbox from @/components/base/radio-groups/radio-group-checkbox. Renders React Aria’s RadioGroup — all of its props are supported.

RadioGroupCheckbox props
PropTypeDefaultDescription
items* (required)RadioGroupItemType[]—The options to choose between. Each renders as a selectable card with a leading checkbox, title, secondary title and description.
size
"sm""md"
"sm"Scales the card spacing, label text and selection checkbox.
Props from React Aria (26)
RadioGroupCheckbox inherited props
PropTypeDefaultDescription
onBlur((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element loses focus.
onFocus((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element receives focus.
onFocusChange((isFocused: boolean) => void)—Handler that is called when the element's focus status changes.
formstring—The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document.
namestring—The name of the input element, used when submitting an HTML form.
defaultValuestring | null—The default value (uncontrolled).
idstring—The element's unique identifier.
isDisabledboolean—Whether the input is disabled.
isInvalidboolean—Whether the input value is invalid.
isReadOnlyboolean—Whether the input can be selected but not changed by the user.
isRequiredboolean—Whether user input is required on the input before form submission.
onChange((value: string) => void)—Handler that is called when the value changes.
orientation
"horizontal""vertical"
"vertical"The axis the Radio Button(s) should align with.
validate((value: string) => ValidationError | true | null | undefined)—A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior
"native""aria"
"native"Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valuestring | null—The current value (controlled).
styleStyleOrFunction<RadioGroupRenderProps>—The inline style for the element. A function may be provided to compute the style based on component state.
childrenChildrenOrFunction<RadioGroupRenderProps>—The children of the component. A function may be provided to alter the children based on component state.
slotstring | null—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
classNameClassNameOrFunction<RadioGroupRenderProps>—The CSS className for the element. A function may be provided to compute the class based on component state.
renderDOMRenderFunction<"div", RadioGroupRenderProps>—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements:
  • You must render the expected element type (e.g. if <button> is expected, you cannot render an <a>).
  • Only a single root DOM element can be rendered (no fragments).
  • You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-errormessagestring—Identifies the element that provides an error message for the object.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

RadioGroupIconCard

Import RadioGroupIconCard from @/components/base/radio-groups/radio-group-icon-card. Renders React Aria’s RadioGroup — all of its props are supported.

RadioGroupIconCard props
PropTypeDefaultDescription
items* (required)IconCardItemType[]—The plans to choose between. Each renders as a two-part card — a header with a featured icon, title and checkbox, and a body with the price, optional badge and description.
size
"sm""md"
"sm"Scales the featured icon, title, price and selection checkbox.
Props from React Aria (26)
RadioGroupIconCard inherited props
PropTypeDefaultDescription
onBlur((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element loses focus.
onFocus((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element receives focus.
onFocusChange((isFocused: boolean) => void)—Handler that is called when the element's focus status changes.
formstring—The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document.
namestring—The name of the input element, used when submitting an HTML form.
defaultValuestring | null—The default value (uncontrolled).
idstring—The element's unique identifier.
isDisabledboolean—Whether the input is disabled.
isInvalidboolean—Whether the input value is invalid.
isReadOnlyboolean—Whether the input can be selected but not changed by the user.
isRequiredboolean—Whether user input is required on the input before form submission.
onChange((value: string) => void)—Handler that is called when the value changes.
orientation
"horizontal""vertical"
"vertical"The axis the Radio Button(s) should align with.
validate((value: string) => ValidationError | true | null | undefined)—A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior
"native""aria"
"native"Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valuestring | null—The current value (controlled).
styleStyleOrFunction<RadioGroupRenderProps>—The inline style for the element. A function may be provided to compute the style based on component state.
childrenChildrenOrFunction<RadioGroupRenderProps>—The children of the component. A function may be provided to alter the children based on component state.
slotstring | null—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
classNameClassNameOrFunction<RadioGroupRenderProps>—The CSS className for the element. A function may be provided to compute the class based on component state.
renderDOMRenderFunction<"div", RadioGroupRenderProps>—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements:
  • You must render the expected element type (e.g. if <button> is expected, you cannot render an <a>).
  • Only a single root DOM element can be rendered (no fragments).
  • You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-errormessagestring—Identifies the element that provides an error message for the object.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

RadioGroupIconSimple

Import RadioGroupIconSimple from @/components/base/radio-groups/radio-group-icon-simple. Renders React Aria’s RadioGroup — all of its props are supported.

RadioGroupIconSimple props
PropTypeDefaultDescription
items* (required)RadioGroupItemType[]—The options to choose between. Each renders as a selectable card with a leading featured icon, title, secondary title and description.
size
"sm""md"
"sm"Scales the featured icon, label text and selection checkbox.
Props from React Aria (26)
RadioGroupIconSimple inherited props
PropTypeDefaultDescription
onBlur((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element loses focus.
onFocus((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element receives focus.
onFocusChange((isFocused: boolean) => void)—Handler that is called when the element's focus status changes.
formstring—The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document.
namestring—The name of the input element, used when submitting an HTML form.
defaultValuestring | null—The default value (uncontrolled).
idstring—The element's unique identifier.
isDisabledboolean—Whether the input is disabled.
isInvalidboolean—Whether the input value is invalid.
isReadOnlyboolean—Whether the input can be selected but not changed by the user.
isRequiredboolean—Whether user input is required on the input before form submission.
onChange((value: string) => void)—Handler that is called when the value changes.
orientation
"horizontal""vertical"
"vertical"The axis the Radio Button(s) should align with.
validate((value: string) => ValidationError | true | null | undefined)—A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior
"native""aria"
"native"Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valuestring | null—The current value (controlled).
styleStyleOrFunction<RadioGroupRenderProps>—The inline style for the element. A function may be provided to compute the style based on component state.
childrenChildrenOrFunction<RadioGroupRenderProps>—The children of the component. A function may be provided to alter the children based on component state.
slotstring | null—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
classNameClassNameOrFunction<RadioGroupRenderProps>—The CSS className for the element. A function may be provided to compute the class based on component state.
renderDOMRenderFunction<"div", RadioGroupRenderProps>—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements:
  • You must render the expected element type (e.g. if <button> is expected, you cannot render an <a>).
  • Only a single root DOM element can be rendered (no fragments).
  • You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-errormessagestring—Identifies the element that provides an error message for the object.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

RadioGroupPaymentIcon

Import RadioGroupPaymentIcon from @/components/base/radio-groups/radio-group-payment-icon. Renders React Aria’s RadioGroup — all of its props are supported.

RadioGroupPaymentIcon props
PropTypeDefaultDescription
items* (required)PaymentCardItemType[]—The saved payment methods to choose between. Each renders as a selectable card with the card logo, title and description.
size
"sm""md"
"sm"Scales the label text, the "Set as default" and "Edit" buttons, and the selection checkbox.
Props from React Aria (26)
RadioGroupPaymentIcon inherited props
PropTypeDefaultDescription
onBlur((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element loses focus.
onFocus((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element receives focus.
onFocusChange((isFocused: boolean) => void)—Handler that is called when the element's focus status changes.
formstring—The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document.
namestring—The name of the input element, used when submitting an HTML form.
defaultValuestring | null—The default value (uncontrolled).
idstring—The element's unique identifier.
isDisabledboolean—Whether the input is disabled.
isInvalidboolean—Whether the input value is invalid.
isReadOnlyboolean—Whether the input can be selected but not changed by the user.
isRequiredboolean—Whether user input is required on the input before form submission.
onChange((value: string) => void)—Handler that is called when the value changes.
orientation
"horizontal""vertical"
"vertical"The axis the Radio Button(s) should align with.
validate((value: string) => ValidationError | true | null | undefined)—A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior
"native""aria"
"native"Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valuestring | null—The current value (controlled).
styleStyleOrFunction<RadioGroupRenderProps>—The inline style for the element. A function may be provided to compute the style based on component state.
childrenChildrenOrFunction<RadioGroupRenderProps>—The children of the component. A function may be provided to alter the children based on component state.
slotstring | null—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
classNameClassNameOrFunction<RadioGroupRenderProps>—The CSS className for the element. A function may be provided to compute the class based on component state.
renderDOMRenderFunction<"div", RadioGroupRenderProps>—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements:
  • You must render the expected element type (e.g. if <button> is expected, you cannot render an <a>).
  • Only a single root DOM element can be rendered (no fragments).
  • You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-errormessagestring—Identifies the element that provides an error message for the object.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

RadioGroupRadioButton

Import RadioGroupRadioButton from @/components/base/radio-groups/radio-group-radio-button. Renders React Aria’s RadioGroup — all of its props are supported.

RadioGroupRadioButton props
PropTypeDefaultDescription
items* (required)RadioGroupItemType[]—The options to choose between. Each renders as a selectable card with a leading radio dot, title, secondary title and description.
size
"sm""md"
"sm"Scales the radio dot, card spacing and label text.
Props from React Aria (26)
RadioGroupRadioButton inherited props
PropTypeDefaultDescription
onBlur((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element loses focus.
onFocus((e: FocusEvent<Element, Element>) => void)—Handler that is called when the element receives focus.
onFocusChange((isFocused: boolean) => void)—Handler that is called when the element's focus status changes.
formstring—The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document.
namestring—The name of the input element, used when submitting an HTML form.
defaultValuestring | null—The default value (uncontrolled).
idstring—The element's unique identifier.
isDisabledboolean—Whether the input is disabled.
isInvalidboolean—Whether the input value is invalid.
isReadOnlyboolean—Whether the input can be selected but not changed by the user.
isRequiredboolean—Whether user input is required on the input before form submission.
onChange((value: string) => void)—Handler that is called when the value changes.
orientation
"horizontal""vertical"
"vertical"The axis the Radio Button(s) should align with.
validate((value: string) => ValidationError | true | null | undefined)—A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior
"native""aria"
"native"Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valuestring | null—The current value (controlled).
styleStyleOrFunction<RadioGroupRenderProps>—The inline style for the element. A function may be provided to compute the style based on component state.
childrenChildrenOrFunction<RadioGroupRenderProps>—The children of the component. A function may be provided to alter the children based on component state.
slotstring | null—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
classNameClassNameOrFunction<RadioGroupRenderProps>—The CSS className for the element. A function may be provided to compute the class based on component state.
renderDOMRenderFunction<"div", RadioGroupRenderProps>—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements:
  • You must render the expected element type (e.g. if <button> is expected, you cannot render an <a>).
  • Only a single root DOM element can be rendered (no fragments).
  • You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-errormessagestring—Identifies the element that provides an error message for the object.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

FAQs

Please refer to our frequently asked questions page for more.

No, radio groups are a PRO component. You need Untitled UI PRO access to install them with npx untitledui@latest add radio-groups. For basic radio inputs, the free radio buttons component is available.

There are six components, each in its own file: RadioGroupIconSimple, RadioGroupIconCard, RadioGroupAvatar, RadioGroupPaymentIcon, RadioGroupRadioButton and RadioGroupCheckbox. All six allow only one selection. RadioGroupCheckbox uses a checkbox-style indicator, but it still behaves as a radio group.

Pass an items array. Most variants expect value, title, secondaryTitle, description and icon on each item. RadioGroupAvatar uses id, name, username, title and avatarUrl. RadioGroupPaymentIcon uses value, title, description and a logo node. Set disabled: true on an item to disable it.

Each variant accepts React Aria's RadioGroup props. Use defaultValue for uncontrolled state, or value with onChange for controlled state. The value is the item's value, or its id for RadioGroupAvatar.

Every variant supports "sm" and "md" through the size prop. The default is "sm". "md" uses larger text, indicators and icons.

The components don't render a visible group label, so pass aria-label as the examples do, or aria-labelledby pointing to your own heading. Keyboard support comes from React Aria: Tab moves focus into the group and the arrow keys change the selection.

By default, options stack vertically using flex flex-col gap-3. Pass layout classes through className, such as flex-row or a grid. They're merged with tailwind-merge, so they replace the default classes that conflict.

Radio buttonsRating badge and stars