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 {RadioModule} from "@qualcomm-ui/angular/radio"

Examples

Simple

The simple API bundles all Radio Item subcomponents together into a single q-radio directive.

<fieldset defaultValue="html" name="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label label="HTML" q-radio value="html"></label>
    <label label="CSS" q-radio value="css"></label>
    <label label="TypeScript" q-radio value="ts"></label>
  </div>
</fieldset>

Child Directives

Provide child directives to customize specific elements while keeping the simple API's default structure.

<fieldset defaultValue="html" name="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label q-radio value="html">
      <div q-radio-label>HTML</div>
    </label>
    <label q-radio value="css">
      <div q-radio-label>CSS</div>
    </label>
    <label q-radio value="ts">
      <div q-radio-label>TypeScript</div>
    </label>
  </div>
</fieldset>

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.

<fieldset defaultValue="html" name="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label q-radio-root value="html">
      <input q-radio-hidden-input />
      <div q-radio-control></div>
      <span q-radio-label>HTML</span>
    </label>
    <label q-radio-root value="css">
      <input q-radio-hidden-input />
      <div q-radio-control></div>
      <span q-radio-label>CSS</span>
    </label>
    <label q-radio-root value="ts">
      <input q-radio-hidden-input />
      <div q-radio-control></div>
      <span q-radio-label>TypeScript</span>
    </label>
  </div>
</fieldset>

Layout

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

<fieldset defaultValue="html" name="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label q-radio-root value="html">
      <input q-radio-hidden-input />
      <span q-radio-label>HTML</span>
      <div q-radio-control></div>
    </label>
    <label q-radio-root value="css">
      <input q-radio-hidden-input />
      <span q-radio-label>CSS</span>
      <div q-radio-control></div>
    </label>
    <label q-radio-root value="ts">
      <input q-radio-hidden-input />
      <span q-radio-label>TypeScript</span>
      <div q-radio-control></div>
    </label>
  </div>
</fieldset>

Disabled

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

Disabled

<fieldset defaultValue="html" disabled name="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label label="HTML" q-radio value="html"></label>
    <label label="CSS" q-radio value="css"></label>
    <label label="TypeScript" q-radio value="ts"></label>
  </div>
</fieldset>

Orientation

Controls the layout direction of radio buttons within the group.

<fieldset name="language" orientation="horizontal" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label label="HTML" q-radio value="html"></label>
    <label label="CSS" q-radio value="css"></label>
    <label label="TypeScript" q-radio value="ts"></label>
  </div>
  <div q-radio-group-error-text>You must select a value</div>
</fieldset>

Sizes

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

small (sm) medium (md) large (lg)

import {Component} from "@angular/core"

import {RadioModule} from "@qualcomm-ui/angular/radio"

@Component({
  imports: [RadioModule],
  selector: "radio-sizes-demo",
  template: `
    <fieldset class="flex flex-col items-center gap-4" q-radio-group>
      <div q-radio-group-items>
        <label label="small (sm)" q-radio size="sm" value="sm"></label>
        <label label="medium (md)" q-radio size="md" value="md"></label>
        <label label="large (lg)" q-radio size="lg" value="lg"></label>
      </div>
    </fieldset>
  `,
})
export class RadioSizesDemo {}

Indented

Use indented to indent the radio items.

<fieldset defaultValue="html" indented name="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label label="HTML" q-radio value="html"></label>
    <label label="CSS" q-radio value="css"></label>
    <label label="TypeScript" q-radio value="ts"></label>
  </div>
</fieldset>

Hint

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

<fieldset defaultValue="html" name="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label label="HTML" q-radio value="html"></label>
    <label label="CSS" q-radio value="css"></label>
    <label label="TypeScript" q-radio value="ts"></label>
  </div>
  <div q-radio-group-hint>You can change this later</div>
</fieldset>

Forms

Template Forms

When using template-driven forms with ngModel, enable validation by adding the required attribute directly to the template:

Guidelines:

When using template forms, add the required attribute to trigger validation
The component automatically handles validation state checking
The q-radio-group-error-text directive displays automatically when the field is invalid and the user has interacted with it

Full example:

<div name="language" q-radio-group required [(ngModel)]="value">
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label label="HTML" q-radio value="html"></label>
    <label label="CSS" q-radio value="css"></label>
    <label label="TypeScript" q-radio value="ts"></label>
  </div>
  <div q-radio-group-error-text>You must select a value</div>
</div>

Reactive Forms

Use Reactive Forms instead of Template-driven Forms for better control over form state and validation.

<fieldset formControlName="language" q-radio-group>
  <div q-radio-group-label>Language</div>
  <div q-radio-group-items>
    <label label="HTML" q-radio value="html"></label>
    <label label="CSS" q-radio value="css"></label>
    <label label="TypeScript" q-radio value="ts"></label>
  </div>
  <div q-radio-group-error-text>You must select a value</div>
</fieldset>

Composition

RadioGroup

The Radio is only intended to be used as direct descendants of the q-radio-group directive.

<!-- Won't work alone ❌ -->
<label q-radio label="Label" value="value"></label>

<!-- Works as expected ✅ -->
<fieldset q-radio-group>
  <label q-radio label="Label" value="value"></label>
</fieldset>

Radio buttons are designed for groups. For single toggle controls, use the Checkbox component instead.

Composite Components

The Radio's composite components are only intended to be used as direct descendants of the q-radio-root directive.

<!-- Won't work alone ❌ -->
<input q-radio-hidden-input />
<span q-radio-control></span>
<span q-radio-label>Label</span>

<!-- Works as expected ✅ -->
<label q-radio-root value="value">
  <input q-radio-hidden-input />
  <span q-radio-control></span>
  <span q-radio-label>Label</span>
</label>

Accessibility

Always use the associated label or q-radio-label directive when authoring each radio item's text label. This is automatically associated with the input element.
If you omit a visible item label, give the radio item an accessible name with aria-label or aria-labelledby on the simple q-radio. If you use the composite API, provide aria-label or aria-labelledby on the q-radio-hidden-input element. Avoid [attr.aria-label] and [attr.aria-labelledby]; use [aria-label] or [aria-labelledby] for dynamic values.

<fieldset defaultValue="email" name="notification" q-radio-group>
  <div q-radio-group-label>Notification preference</div>
  <div q-radio-group-items>
    <label aria-label="Email" q-radio value="email"></label>
    <label aria-label="SMS" q-radio value="sms"></label>
    <label aria-label="Push" q-radio value="push"></label>
  </div>
</fieldset>

Explorer

Component Anatomy

Hover to highlight, click to view API

group label items item item-control item-label hint

Prop	Type	Default
defaultValue The initial value of the radio group when rendered. Use when you don't need to control the state of the radio group. This property will be ignored if you opt into controlled state via form control bindings.	string
dir The document's text/writing direction.	'ltr' \| 'rtl'	"ltr"
disabled Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.	boolean
getRootNode A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string
indented Indents the radio items.	boolean	false
name The name of the input field in a radio group. Useful for form submission.	string
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
required Controls whether the input is required in template-driven forms. 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'
(valueChanged) Event emitted when the radio is selected or deselected. This is only emitted on interaction. It doesn't emit in response to programmatic or form control changes.	string

The initial value of the radio group when rendered. Use when you don't need to control the state of the radio group. This property will be ignored if you opt into controlled state via form control bindings.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

indented

Type

boolean

Description

Indents the radio items.

name

Type

string

Description

The name of the input field in a radio group. Useful for form submission.

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.

required

Type

boolean

Description

Controls whether the input is required in template-driven forms. 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.

(valueChanged)

Type

string

Description

Event emitted when the radio is selected or deselected. This is only emitted on interaction. It doesn't emit in response to programmatic or form control changes.

Attribute / Property	Value
`class`	'qui-radio-group__root'
`data-disabled`
`data-orientation`	\| 'horizontal' \| 'vertical'
`data-radio-part`	'group'

class

Value

'qui-radio-group__root'

data-disabled

Value

data-orientation

Value

| 'horizontal'
| 'vertical'

data-radio-part

Value

'group'

q-radio-group-label

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`class`	'qui-radio-group__label'
`data-disabled`
`data-radio-part`	'label'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-radio-group__label'

data-disabled

Value

data-radio-part

Value

'label'

data-size

Value

| 'sm'
| 'md'
| 'lg'

q-radio-group-items

Attribute / Property	Value
`class`	'qui-radio-group__items'
`data-indented`
`data-orientation`	\| 'horizontal' \| 'vertical'
`data-radio-part`	'items'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-radio-group__items'

data-indented

Value

data-orientation

Value

| 'horizontal'
| 'vertical'

data-radio-part

Value

'items'

data-size

Value

| 'sm'
| 'md'
| 'lg'

q-radio-group-hint

Hint text displayed below the radio group.

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

q-radio-group-error-text

Prop	Type	Default
icon Error indicator icon.	\| LucideIconData \| string	CircleAlert
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

icon

Type

| LucideIconData
| string

Description

Error indicator icon.

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

Attribute / Property	Value
`class`	'qui-input__error-text'
`data-radio-part`	'error-text'
`hidden`	boolean

q-radio

The q-radio directive supports all props from q-radio-root directive, plus the props listed below.

Prop	Type
aria-label v2.9.0 Accessible label applied to the generated hidden input when no visible label is provided.	string
aria-labelledby v2.9.0 ID reference for an external item label applied to the generated hidden input.	string
hint Optional hint text displayed below the radio. Hints are hidden when the radio is invalid.	string

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

aria-label

v2.9.0

Type

string

Description

Accessible label applied to the generated hidden input when no visible label is provided.

aria-labelledby

v2.9.0

Type

string

Description

ID reference for an external item label applied to the generated hidden input.

hint

Type

string

Description

Optional hint text displayed below the radio. Hints are hidden when the radio is invalid.

label

Type

string

Description

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

Composite API

q-radio-root

Prop	Type	Default
value ^* The value of the radio input. This is used to identify which radio is selected in a group.	string
disabled Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.	boolean

id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string
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

Description

The value of the radio input. This is used to identify which radio is selected in a group.

disabled

Type

boolean

Description

Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

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.

Attribute / Property	Value
`class`	'qui-radio__root'
`data-disabled`
`data-focus`
`data-focus-visible`
`data-hover`
`data-invalid`
`data-radio-part`	'item'
`data-readonly`
`data-state`	\| 'checked' \| 'unchecked'

class

Value

'qui-radio__root'

data-disabled

Value

data-focus

Value

data-focus-visible

Value

data-hover

Value

data-invalid

Value

data-radio-part

Value

'item'

data-readonly

Value

data-state

Value

| 'checked'
| 'unchecked'

q-radio-label

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`class`	'qui-radio__label'
`data-disabled`
`data-focus`
`data-focus-visible`
`data-hover`
`data-invalid`
`data-radio-part`	'item-label'
`data-readonly`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'checked' \| 'unchecked'

class

Value

'qui-radio__label'

data-disabled

Value

data-focus

Value

data-focus-visible

Value

data-hover

Value

data-invalid

Value

data-radio-part

Value

'item-label'

data-readonly

Value

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

| 'checked'
| 'unchecked'

q-radio-control

Attribute / Property	Value
`class`	'qui-radio__control'
`data-active`
`data-disabled`
`data-focus`
`data-focus-visible`
`data-hover`
`data-invalid`
`data-radio-part`	'item-control'
`data-readonly`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'checked' \| 'unchecked'

class

Value

'qui-radio__control'

data-active

Value

data-disabled

Value

data-focus

Value

data-focus-visible

Value

data-hover

Value

data-invalid

Value

data-radio-part

Value

'item-control'

data-readonly

Value

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

| 'checked'
| 'unchecked'

q-radio-hidden-input

Prop	Type
aria-label v2.4.0 ARIA label applied to the hidden input.	string
aria-labelledby v2.4.0 ID reference for an external item label applied to the hidden input.	string
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

aria-label

v2.4.0

Type

string

Description

ARIA label applied to the hidden input.

aria-labelledby

v2.4.0

Type

string

Description

ID reference for an external item label applied to the hidden input.

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`class`	'qui-radio__hidden-input'
`data-disabled`
`data-focus`
`data-focus-visible`
`data-hover`
`data-invalid`
`data-ownedby`	string
`data-radio-part`	'item-hidden-input'
`data-readonly`
`data-state`	\| 'checked' \| 'unchecked'
`style`	CSSProperties

class

Value

'qui-radio__hidden-input'

data-disabled

Value

data-focus

Value

data-focus-visible

Value

data-hover

Value

data-invalid

Value

data-ownedby

Value

string

data-radio-part

Value

'item-hidden-input'

data-readonly

Value

data-state

Value

| 'checked'
| 'unchecked'

style

Value

CSSProperties

q-radio-hint

Hint text displayed below the radio.

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

Attribute / Property	Value
`class`	'qui-input__hint'
`data-disabled`
`data-focus`
`data-focus-visible`
`data-hover`
`data-invalid`
`data-radio-part`	'item-hint'
`data-readonly`
`data-state`	\| 'checked' \| 'unchecked'
`hidden`	boolean

class

Value

'qui-input__hint'

data-disabled

Value

data-focus

Value

data-focus-visible

Value

data-hover

Value

data-invalid

Value

data-radio-part

Value

'item-hint'

data-readonly

Value

data-state

Value

| 'checked'
| 'unchecked'

hidden

Value

boolean

Last updated on May 22, 2026 by Ryan Bower

Progress Ring

Segmented Control