Getting Started
InstallationVersioning
Integrations
ESLintTailwind CSS
Theming & Patterns
Composition
Polymorphic ComponentsRender Props
Components
OverviewAccordionAlert Banner
AvatarBreadcrumbsButtonButton GroupCard
Beta
CheckboxCheckbox Group
CollapsibleComboboxDialogDividerDrawerFile Input
Beta
Header BarIconIcon ButtonInline Icon ButtonInline Notification
LinkMenuNumber InputPaginationPassword InputPopoverProgressProgress RingRadioSegmented ControlSelectSide NavSliderStepper
Beta
SwitchSwitch Group
TableTabsTagText Area
Text InputToast NotificationTooltipTree

Radio

Radio buttons are essential form controls that present users with a clear set of options where only one selection is possible at a time.

import {Radio, RadioGroup} from "@qualcomm-ui/react/radio"

Examples

Simple

Basic radio with label using the simple API.

Language
<RadioGroup.Root defaultValue="html">
  <RadioGroup.Label>Language</RadioGroup.Label>
  <RadioGroup.Items>
    <Radio label="HTML" value="html" />
    <Radio label="CSS" value="css" />
    <Radio label="TypeScript" value="ts" />
  </RadioGroup.Items>
</RadioGroup.Root>

Composite

Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.

Language
<RadioGroup.Root defaultValue="html" name="language">
  <RadioGroup.Label>Language</RadioGroup.Label>
  <RadioGroup.Items>
    <Radio.Root value="html">
      <Radio.Control />
      <Radio.HiddenInput />
      <Radio.Label>HTML</Radio.Label>
    </Radio.Root>
    <Radio.Root value="css">
      <Radio.Control />
      <Radio.HiddenInput />
      <Radio.Label>CSS</Radio.Label>
    </Radio.Root>
    <Radio.Root value="ts">
      <Radio.Control />
      <Radio.HiddenInput />
      <Radio.Label>TypeScript</Radio.Label>
    </Radio.Root>
  </RadioGroup.Items>
</RadioGroup.Root>

Layout

Use the composite API when you need to modify the layout of the radio buttons.

Language
<RadioGroup.Root defaultValue="html" name="language">
  <RadioGroup.Label>Language</RadioGroup.Label>
  <RadioGroup.Items>
    <Radio.Root value="html">
      <Radio.HiddenInput />
      <Radio.Label>HTML</Radio.Label>
      <Radio.Control />
    </Radio.Root>
    <Radio.Root value="css">
      <Radio.HiddenInput />
      <Radio.Label>CSS</Radio.Label>
      <Radio.Control />
    </Radio.Root>
    <Radio.Root value="ts">
      <Radio.HiddenInput />
      <Radio.Label>TypeScript</Radio.Label>
      <Radio.Control />
    </Radio.Root>
  </RadioGroup.Items>
</RadioGroup.Root>

Disabled

When disabled is true, the radio group becomes non-interactive and is typically rendered with reduced opacity to indicate its unavailable state.

Disabled
<RadioGroup.Root defaultValue="html" disabled name="language">
  <RadioGroup.Items>
    <Radio label="HTML" value="html" />
    <Radio label="CSS" value="css" />
    <Radio label="TypeScript" value="ts" />
  </RadioGroup.Items>
</RadioGroup.Root>

Controlled State

Set the initial value using the defaultValue prop, or use value and onValueChange to control the value manually. These props follow our controlled state pattern.

import {type ReactElement, useState} from "react"

import {Radio, RadioGroup} from "@qualcomm-ui/react/radio"

export function RadioControlledDemo(): ReactElement {
  const [value, setValue] = useState<string | null>("html")

  return (
    <form>
      <RadioGroup.Root
        name="language"
        onValueChange={(nextValue) => {
          console.log("radio value change:", nextValue)
          setValue(nextValue)
        }}
        value={value}
      >
        <RadioGroup.Items>
          <Radio label="HTML" value="html" />
          <Radio label="CSS" value="css" />
          <Radio label="TypeScript" value="ts" />
        </RadioGroup.Items>
      </RadioGroup.Root>
    </form>
  )
}

Orientation

Controls the layout direction of radio buttons within the group.

Language
<RadioGroup.Root
  defaultValue="html"
  name="language"
  orientation="horizontal"
>
  <RadioGroup.Label>Language</RadioGroup.Label>
  <RadioGroup.Items>
    <Radio label="HTML" value="html" />
    <Radio label="CSS" value="css" />
    <Radio label="TypeScript" value="ts" />
  </RadioGroup.Items>
</RadioGroup.Root>

Sizes

The radio supports three sizes: sm, md (default), and lg.

<RadioGroup.Root defaultValue="html">
  <RadioGroup.Items>
    <Radio label="small (sm)" size="sm" value="sm" />
    <Radio label="medium (md)" size="md" value="md" />
    <Radio label="large (lg)" size="lg" value="lg" />
  </RadioGroup.Items>
</RadioGroup.Root>

Indented

Use the indented prop to indent the radio items.

Language
<RadioGroup.Root defaultValue="html" indented name="language">
  <RadioGroup.Label>Language</RadioGroup.Label>
  <RadioGroup.Items>
    <Radio label="HTML" value="html" />
    <Radio label="CSS" value="css" />
    <Radio label="TypeScript" value="ts" />
  </RadioGroup.Items>
</RadioGroup.Root>

Hint

Add a hint to provide additional context for the radio group.

Language
You can change this later
<RadioGroup.Root defaultValue="html">
  <RadioGroup.Label>Language</RadioGroup.Label>
  <RadioGroup.Items>
    <Radio label="HTML" value="html" />
    <Radio label="CSS" value="css" />
    <Radio label="TypeScript" value="ts" />
  </RadioGroup.Items>
  <RadioGroup.Hint>You can change this later</RadioGroup.Hint>
</RadioGroup.Root>

Forms

Choose the form library that fits your needs—we've built examples with React Hook Form and Tanstack Form to get you started.

React Hook Form

Use React Hook Form to handle the radio state and validation. ArkType works great for schema validation if you need it.

Programming Language
Framework
import type {ReactElement} from "react"

import {arktypeResolver} from "@hookform/resolvers/arktype"
import {type} from "arktype"
import {Controller, useForm} from "react-hook-form"

import {Button} from "@qualcomm-ui/react/button"
import {Radio, RadioGroup} from "@qualcomm-ui/react/radio"

interface FormData {
  framework: string
  language: string
}

const FormSchema = type({
  framework: "string>0",
  language: "string>0",
})

export function RadioReactHookFormDemo(): ReactElement {
  const {control, handleSubmit} = useForm<FormData>({
    defaultValues: {
      framework: "",
      language: "",
    },
    resolver: arktypeResolver(FormSchema),
  })

  return (
    <form
      className="flex w-56 flex-col gap-4"
      onSubmit={(e) => {
        void handleSubmit((data) => console.log(data))(e)
      }}
    >
      <Controller
        control={control}
        name="language"
        render={({
          field: {name, onChange, value, ...fieldProps},
          fieldState: {error},
        }) => {
          return (
            <RadioGroup.Root
              invalid={!!error}
              name={name}
              onValueChange={onChange}
              value={value}
              {...fieldProps}
            >
              <RadioGroup.Label>Programming Language</RadioGroup.Label>
              <RadioGroup.Items>
                <Radio label="JavaScript" value="javascript" />
                <Radio label="TypeScript" value="typescript" />
                <Radio label="Python" value="python" />
              </RadioGroup.Items>
              <RadioGroup.ErrorText>{error?.message}</RadioGroup.ErrorText>
            </RadioGroup.Root>
          )
        }}
      />

      <Controller
        control={control}
        name="framework"
        render={({
          field: {name, onChange, value, ...fieldProps},
          fieldState: {error},
        }) => {
          return (
            <RadioGroup.Root
              invalid={!!error}
              name={name}
              onValueChange={onChange}
              value={value}
              {...fieldProps}
            >
              <RadioGroup.Label>Framework</RadioGroup.Label>
              <RadioGroup.Items>
                <Radio label="React" value="react" />
                <Radio label="Vue" value="vue" />
                <Radio label="Angular" value="angular" />
              </RadioGroup.Items>
              <RadioGroup.ErrorText>{error?.message}</RadioGroup.ErrorText>
            </RadioGroup.Root>
          )
        }}
      />

      <Button
        className="mt-1"
        emphasis="primary"
        size="sm"
        type="submit"
        variant="fill"
      >
        Submit
      </Button>
    </form>
  )
}

Tanstack Form

Tanstack Form handles radio validation with its built-in validators.

Programming Language
Framework
import type {ReactElement} from "react"

import {useForm} from "@tanstack/react-form"

import {Button} from "@qualcomm-ui/react/button"
import {Radio, RadioGroup} from "@qualcomm-ui/react/radio"

interface FormData {
  framework: string | null
  language: string | null
}

const defaultFormData: FormData = {
  framework: "",
  language: "",
}

const requiredMessage = "Please select an option"

export function RadioTanstackFormDemo(): ReactElement {
  const form = useForm({
    defaultValues: defaultFormData,
    onSubmit: ({value}) => {
      console.log(value)
    },
  })

  return (
    <form
      className="flex w-56 flex-col gap-4"
      onSubmit={(event) => {
        event.preventDefault()
        event.stopPropagation()
        void form.handleSubmit()
      }}
    >
      <form.Field
        name="language"
        validators={{
          onChange: (field) => (field.value ? undefined : requiredMessage),
          onSubmit: (field) => (field.value ? undefined : requiredMessage),
        }}
      >
        {({handleChange, name, state}) => {
          const fieldError =
            state.meta.errorMap["onChange"] || state.meta.errorMap["onSubmit"]
          return (
            <RadioGroup.Root
              invalid={!!fieldError}
              name={name}
              onValueChange={handleChange}
              value={state.value}
            >
              <RadioGroup.Label>Programming Language</RadioGroup.Label>
              <RadioGroup.Items>
                <Radio label="JavaScript" value="javascript" />
                <Radio label="TypeScript" value="typescript" />
                <Radio label="Python" value="python" />
              </RadioGroup.Items>
              <RadioGroup.ErrorText>{fieldError}</RadioGroup.ErrorText>
            </RadioGroup.Root>
          )
        }}
      </form.Field>

      <form.Field
        name="framework"
        validators={{
          onChange: (field) => (field.value ? undefined : requiredMessage),
          onSubmit: (field) => (field.value ? undefined : requiredMessage),
        }}
      >
        {({handleChange, name, state}) => {
          const fieldError =
            state.meta.errorMap["onChange"] || state.meta.errorMap["onSubmit"]
          return (
            <RadioGroup.Root
              invalid={!!fieldError}
              name={name}
              onValueChange={handleChange}
              value={state.value}
            >
              <RadioGroup.Label>Framework</RadioGroup.Label>
              <RadioGroup.Items>
                <Radio label="React" value="react" />
                <Radio label="Vue" value="vue" />
                <Radio label="Angular" value="angular" />
              </RadioGroup.Items>
              <RadioGroup.ErrorText>{fieldError}</RadioGroup.ErrorText>
            </RadioGroup.Root>
          )
        }}
      </form.Field>

      <Button
        className="mt-1"
        emphasis="primary"
        size="sm"
        type="submit"
        variant="fill"
      >
        Submit
      </Button>
    </form>
  )
}

Tanstack form also supports ArkType.

Guidelines

RadioGroup

The Radio is only intended to be used as direct descendants of the <RadioGroup.Root> component.

/* Won't work alone ❌ */
<Radio label="Label" value="value" />

/* Works as expected ✅ */
<RadioGroup.Root>
  <Radio label="Label" value="value" />
</RadioGroup.Root>

Composite Components

The Radio's composite components are only intended to be used as direct descendants of the <Radio.Root> component.

/* Won't work alone ❌ */
<Radio.HiddenInput />
<Radio.Control />

/* Works as expected ✅ */
<Radio.Root>
  <Radio.HiddenInput />
  <Radio.Control />
</Radio.Root>

Explorer

Language
You can change this later

Component Anatomy

Hover to highlight, click to view API

grouplabelitemsitemitem-controlitem-labelhint

API

<RadioGroup.Root>

PropTypeDefault
children
React children prop.
ReactNode
defaultValue
The initial value of the checked radio when rendered. Use when you don't need to control the value of the radio group.
string
dir
The document's text/writing direction.
'ltr' | 'rtl'
'ltr'
disabled
Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.
boolean
form
The id of the form that the input belongs to.
string
getRootNode
A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.
    () =>
    | Node
    | ShadowRoot
    | Document
    indented
    Indents the radio items. Only used at radio group level.
    boolean
    false
    invalid
    Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.
    boolean
    name
    The name of the input field. Useful for form submission.
    string
    onValueChange
    Function called once a radio is checked
      (
        value: string,
      ) => void
      orientation
      Orientation of the radio group
      | 'horizontal'
      | 'vertical'
      'vertical'
      readOnly
      Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.
      boolean
      render
      Allows you to replace the component's HTML element with a different tag or component. Learn more
      | ReactElement
      | ((
          props: object,
        ) => ReactElement)
      required
      Whether the input is required. When true, the input must have a value for form validation to pass.
      boolean
      size
      The size of the radio and its elements. Governs properties like label font size, control size, and indicator size.
      | 'sm'
      | 'md'
      | 'lg'
      'md'
      value
      The controlled value of the radio group
      string
      children
      Type
      ReactNode
      Description
      React children prop.
      defaultValue
      Type
      string
      Description
      The initial value of the checked radio when rendered. Use when you don't need to control the value of the radio group.
      dir
      Type
      'ltr' | 'rtl'
      Description
      The document's text/writing direction.
      disabled
      Type
      boolean
      Description
      Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.
      form
      Type
      string
      Description
      The id of the form that the input belongs to.
      getRootNode
      Type
      () =>
      | Node
      | ShadowRoot
      | Document
      Description
      A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.
        indented
        Type
        boolean
        Description
        Indents the radio items. Only used at radio group level.
        invalid
        Type
        boolean
        Description
        Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.
        name
        Type
        string
        Description
        The name of the input field. Useful for form submission.
        onValueChange
        Type
        (
          value: string,
        ) => void
        Description
        Function called once a radio is checked
          orientation
          Type
          | 'horizontal'
          | 'vertical'
          Description
          Orientation of the radio group
          readOnly
          Type
          boolean
          Description
          Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          required
          Type
          boolean
          Description
          Whether the input is required. When true, the input must have a value for form validation to pass.
          size
          Type
          | 'sm'
          | 'md'
          | 'lg'
          Description
          The size of the radio and its elements. Governs properties like label font size, control size, and indicator size.
          value
          Type
          string
          Description
          The controlled value of the radio group

          <RadioGroup.Label>

          PropType
          children
          React children prop.
          ReactNode
          id
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          string
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          children
          Type
          ReactNode
          Description
          React children prop.
          id
          Type
          string
          Description
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more

          <RadioGroup.Items>

          PropType
          children
          React children prop.
          ReactNode
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          children
          Type
          ReactNode
          Description
          React children prop.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more

          <RadioGroup.Hint>

          PropType
          children
          React children prop.
          ReactNode
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          children
          Type
          ReactNode
          Description
          React children prop.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more

          <RadioGroup.ErrorText>

          PropType
          children
          React children prop.
          ReactNode
          icon
          An icon to display next to the error text.
          | LucideIcon
          | ReactNode
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          children
          Type
          ReactNode
          Description
          React children prop.
          icon
          Type
          | LucideIcon
          | ReactNode
          Description
          An icon to display next to the error text.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more

          <Radio>

          The Radio component supports all props from Radio.Root, plus the additional props listed below.

          PropType
          aria-label
          aria-label attribute, forwarded to the hidden input element.
          string
          aria-labelledby
          aria-labelledby attribute, forwarded to the hidden input element. If you provide a label, omit this prop.
          string
          controlProps
          Props applied to the control element.
          RadioControlProps
          hiddenInputProps
          Props applied to the hidden input element.
          RadioHiddenInputProps
          hint
          Optional hint text that describes the element.
          ReactNode
          hintProps
          Props applied to the hint element.
          RadioHintProps
          label
          Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.
          ReactNode
          labelProps
          Props applied to the label element.
          RadioLabelProps
          aria-label
          Type
          string
          Description
          aria-label attribute, forwarded to the hidden input element.
          aria-labelledby
          Type
          string
          Description
          aria-labelledby attribute, forwarded to the hidden input element. If you provide a label, omit this prop.
          controlProps
          Type
          RadioControlProps
          Description
          Props applied to the control element.
          hiddenInputProps
          Type
          RadioHiddenInputProps
          Description
          Props applied to the hidden input element.
          hint
          Type
          ReactNode
          Description
          Optional hint text that describes the element.
          hintProps
          Type
          RadioHintProps
          Description
          Props applied to the hint element.
          label
          Type
          ReactNode
          Description
          Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.
          labelProps
          Type
          RadioLabelProps
          Description
          Props applied to the label element.

          <Radio.Root>

          PropTypeDefault
          value
          *
          string
          children
          React children prop.
          ReactNode
          disabled
          boolean
          id
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          string
          indented
          Indents the radio items. Only used at radio group level.
          boolean
          false
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          size
          The size of the radio and its elements. Governs properties like label font size, control size, and indicator size.
          | 'sm'
          | 'md'
          | 'lg'
          'md'
          value
          *
          Type
          string
          children
          Type
          ReactNode
          Description
          React children prop.
          disabled
          Type
          boolean
          id
          Type
          string
          Description
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          indented
          Type
          boolean
          Description
          Indents the radio items. Only used at radio group level.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          size
          Type
          | 'sm'
          | 'md'
          | 'lg'
          Description
          The size of the radio and its elements. Governs properties like label font size, control size, and indicator size.

          <Radio.Label>

          PropType
          children
          React children prop.
          ReactNode
          id
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          string
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          children
          Type
          ReactNode
          Description
          React children prop.
          id
          Type
          string
          Description
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more

          <Radio.Control>

          PropType
          children
          React children prop.
          ReactNode
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          children
          Type
          ReactNode
          Description
          React children prop.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more

          <Radio.HiddenInput>

          <Radio.Hint>

          A help message displayed below the radio. Renders a <div> element by default.
          PropType
          children
          React children prop.
          ReactNode
          id
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          string
          render
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          children
          Type
          ReactNode
          Description
          React children prop.
          id
          Type
          string
          Description
          id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
          render
          Type
          | ReactElement
          | ((
              props: object,
            ) => ReactElement)
          Description
          Allows you to replace the component's HTML element with a different tag or component. Learn more
          Last updated on by Olaf Kappes
          Progress Ring
          Segmented Control
          Examples
          Simple
          Composite
          Layout
          Disabled
          Controlled State
          Orientation
          Sizes
          Indented
          Hint
          Forms
          React Hook Form
          Tanstack Form
          Guidelines
          RadioGroup
          Composite Components
          Explorer
          API
          <RadioGroup.Root>
          <RadioGroup.Label>
          <RadioGroup.Items>
          <RadioGroup.Hint>
          <RadioGroup.ErrorText>
          <Radio>
          <Radio.Root>
          <Radio.Label>
          <Radio.Control>
          <Radio.HiddenInput>
          <Radio.Hint>
          Copyright © 2026 QUALCOMM incorporated. All rights reserved. This site is built with QUI Docs. Head over to the template repository to start building.