Radio

A control element that allows the user to choose only one of a predefined set of mutually exclusive options. The singular property of a radio button makes it distinct from checkboxes, where the user can select and unselect any number of items.

import {QRadioGroup, QRadio} from "@qui/react"

Accessibility

Our radio component is accessible by default.

When you supply the label prop, it is automatically associated with the input element.
If you omit the label, it's recommended that you provide an aria-label using the inputProps prop:

<QRadio inputProps={{"aria-label": "TypeScript"}} value="typescript" />

Examples

Showcase

The QRadio component is rendered as a child of the QRadioGroup component, which handles state and form control bindings. The QRadioGroup component extends the fieldset element for optimal accessibility.

import {ReactNode} from "react"

import {QRadio, QRadioGroup} from "@qui/react"

export default function Showcase(): ReactNode {
  return (
    <form className="grid justify-center">
      <QRadioGroup className="flex gap-4" defaultValue="html" name="language">
        <QRadio label="HTML" value="html" />
        <QRadio label="CSS" value="css" />
        <QRadio label="TypeScript" value="ts" />
      </QRadioGroup>
    </form>
  )
}

Controlled State

The component can be controlled or uncontrolled.

When you supply the onChange and value props, the component is controlled. Otherwise, the component is uncontrolled and the value is tracked internally.

Learn more about controlled and uncontrolled components in the related React Documentation.

Favorite Language:html

HTMLCSSTypeScript

import {ChangeEvent, ReactNode, useState} from "react"

import {QRadio, QRadioGroup} from "@qui/react"

export default function Controlled(): ReactNode {
  const [value, setValue] = useState<string>("html")

  const handleChange = (
    event: ChangeEvent<HTMLInputElement>,
    value: string,
  ) => {
    setValue(value)
  }

  return (
    <div className="grid justify-center gap-4">
      <div className="grid gap-2">
        <div className="flex gap-1">
          <span className="text-primary q-font-metadata-lg">
            Favorite Language:
          </span>
          <span className="text-primary q-font-metadata-lg">{value}</span>
        </div>

        <QRadioGroup
          className="flex gap-4"
          onChange={handleChange}
          value={value}
        >
          <QRadio label="HTML" value="html" />
          <QRadio label="CSS" value="css" />
          <QRadio label="TypeScript" value="ts" />
        </QRadioGroup>
      </div>
    </div>
  )
}

Union Type

The type of the value emitted by the change event aligns with the type of the value property. Here’s an illustration using a union type:

Favorite Language:html

HTMLCSSTypeScript

import {ChangeEvent, ReactNode, useState} from "react"

import {QRadio, QRadioGroup} from "@qui/react"

type WebLanguage = "html" | "css" | "ts"

export default function UnionType(): ReactNode {
  const [value, setValue] = useState<WebLanguage>("html")

  const handleChange = (
    event: ChangeEvent<HTMLInputElement>,
    // the change event's value type matches the type of the `value` prop.
    value: WebLanguage,
  ) => {
    setValue(value)
  }

  return (
    <div className="grid justify-center gap-4">
      <div className="grid gap-2">
        <div className="flex gap-1">
          <span className="text-primary q-font-metadata-lg">
            Favorite Language:
          </span>
          <span className="text-primary q-font-metadata-lg">{value}</span>
        </div>

        <QRadioGroup
          className="flex gap-4"
          onChange={handleChange}
          value={value}
        >
          <QRadio label="HTML" value="html" />
          <QRadio label="CSS" value="css" />
          <QRadio label="TypeScript" value="ts" />
        </QRadioGroup>
      </div>
    </div>
  )
}

API

QRadioGroup

Name & Description	Option(s)	Default
as The component used for the root node. It can be a React component or element.	\| ElementType \| ComponentType	'fieldset'
children React children prop.	ReactNode
className The className property of the Element interface gets and sets the value of the class attribute of the specified element.	string
defaultValue Default value.	string
disabled If true, the component will not be interactive and will appear dimmed.	boolean	false
form Specifies the id of the `<form>` this input belongs to. If omitted, it’s the closest parent form.	string
name Specifies the name for this input that’s submitted with the form.	string
onChange An Event handler function. Required for controlled inputs. Fires immediately when the input’s value is changed by the user (for example, it fires on every keystroke). Behaves like the browser input event	( event: ChangeEvent<HTMLInputElement>, value: Value, ) => void
readOnly If true, the component is not editable by the user.	boolean	false
role HTML role attribute applied to the host element.	string	'radiogroup'
style The style global attribute contains CSS styling declarations to be applied to the element.	CSSProperties
value Controlled value for this radio group.	string

Type

| ElementType
| ComponentType

Default

'fieldset'

Description

The component used for the root node. It can be a React component or element.

children

Type

ReactNode

Description

React children prop.

className

Type

string

Description

The className property of the Element interface gets and sets the value of the class attribute of the specified element.

defaultValue

Type

string

Description

Default value.

disabled

Type

boolean

Default

false

Description

If true, the component will not be interactive and will appear dimmed.

form

Type

string

Description

Specifies the id of the <form> this input belongs to. If omitted, it’s the closest parent form.

name

Type

string

Description

Specifies the name for this input that’s submitted with the form.

onChange

Type

(
  event: ChangeEvent<HTMLInputElement>,
  value: Value,
) => void

Description

An Event handler function. Required for controlled inputs. Fires immediately when the input’s value is changed by the user (for example, it fires on every keystroke). Behaves like the browser input event

readOnly

Type

boolean

Default

false

Description

If true, the component is not editable by the user.

role

Type

string

Default

'radiogroup'

Description

HTML role attribute applied to the host element.

style

Type

CSSProperties

Description

The style global attribute contains CSS styling declarations to be applied to the element.

value

Type

string

Description

Controlled value for this radio group.

QRadio

Name & Description	Option(s)	Default
value ^* Unique value that identifies this radio.	string
as The component used for the root node. It can be a React component element.	\| ElementType \| ComponentType	'span'
autoFocus If `true`, React will focus the component on mount.	boolean
className The className property of the Element interface gets and sets the value of the class attribute of the specified element.	string
defaultChecked A boolean. Specifies the initial value for type="checkbox" and type="radio" inputs.	boolean
disabled If true, the component will not be interactive and will appear dimmed.	boolean	false
form Specifies the id of the `<form>` this input belongs to. If omitted, it’s the closest parent form.	string
id Controlled id. If omitted, a unique identifier will be automatically generated for error, label, and hint accessibility.	string
inputProps attributes applied to the `input` element. Use with caution.	InputHTMLAttributes<HTMLInputElement>	{}
inputRef Pass a ref to the input element.	Ref<HTMLInputElement>
label Optional label describing the radio. Recommended. This property is automatically associated with the component's input element for optimal accessibility.	ReactNode
name Specifies the name for this input that’s submitted with the form.	string
onBlur An Event handler function. Fires when the input element loses focus.	FocusEventHandler<HTMLInputElement>
onChange An Event handler function. Required for controlled inputs. Fires immediately when the input’s value is changed by the user (for example, it fires on every keystroke). Behaves like the browser input event.	ChangeEventHandler<HTMLInputElement>
onFocus An Event handler function. Fires when the input element gains focus.	FocusEventHandler<HTMLInputElement>
readOnly If true, the component is not editable by the user.	boolean	false
style The style global attribute contains CSS styling declarations to be applied to the element.	CSSProperties

value

Type

string

Description

Unique value that identifies this radio.

Type

| ElementType
| ComponentType

Default

'span'

Description

The component used for the root node. It can be a React component element.

autoFocus

Type

boolean

Description

If true, React will focus the component on mount.

className

Type

string

Description

The className property of the Element interface gets and sets the value of the class attribute of the specified element.

defaultChecked

Type

boolean

Description

A boolean. Specifies the initial value for type="checkbox" and type="radio" inputs.

disabled

Type

boolean

Default

false

Description

If true, the component will not be interactive and will appear dimmed.

form

Type

string

Description

Specifies the id of the <form> this input belongs to. If omitted, it’s the closest parent form.

Type

string

Description

Controlled id. If omitted, a unique identifier will be automatically generated for error, label, and hint accessibility.

inputProps

Type

InputHTMLAttributes<HTMLInputElement>

Default

{}

Description

attributes applied to the input element. Use with caution.

inputRef

Type

Ref<HTMLInputElement>

Description

Pass a ref to the input element.

label

Type

ReactNode

Description

Optional label describing the radio. Recommended. This property is automatically associated with the component's input element for optimal accessibility.

name

Type