Skip to main content

Radio

Radio elements are rendered as circles that are filled when selected. They are generally used in radio groups — collections of radio buttons describing a set of related options.

Only one radio button in a given radio group can be selected at the same time.

— Definition from the MDN web docs

Radio vs. checkbox​

Use radio buttons when there is a list of two or more options that are mutually exclusive, and the user must select exactly one choice.

Use [checkboxes][checkbox] when there are lists of options, and the user may select any number of choices, including zero, one, or several.

Radios always have a default selection, whereas checkboxes often default to having none of the options selected.

See this NNGroup article for an in-depth discussion about those differences.

Radio vs. dropdown​

Use radio buttons when there are five or fewer options. Radio buttons have a lower cognitive load because they make all options permanently visible so that users can easily compare them.

Use a [dropdown][] when there are more than five options, showing 15 items when opened.

Text​

The text property sets the label displayed on the radio:

Loading...
Live Editor
<qds-radio text="I am selected" checked></qds-radio>

Writing guidelines​

  • Use positive and active wording for the label so that it's clear what will happen if the user turns on the checkbox
  • Keep labels short to make them scannable
  • Make sure the options are comprehensive and clearly distinct. If it's impossible to be comprehensive, offer a button labeled "Other," supplemented by a type-in field.

Checked​

Use the checked attribute to select the default radio button:

Loading...
Live Editor
<div class="qds-controls qds-related">
  <qds-radio name="checked-demo" checked text="Checked"></qds-radio>
  <qds-radio name="checked-demo" text="Unchecked"></qds-radio>
</div>

Always offer a default selection for radio button lists. By definition, radio buttons always have exactly one option selected, and you therefore shouldn't display them without a default selection.

Use radio buttons only to change settings, not as action buttons that make something happen. Also, the changed settings should not take effect until the user clicks the confirmation button.

See this NNGroup article for more guidance on default selection.

Size​

Radio buttons follow the transversal control size principles. Use the standard size unless you're in one of the specific contexts described on that page.

Loading...
Live Editor
<div class="qds-controls qds-related">
  <div class="qds-controls qds-related flex flex-row">
    <qds-label inline text="Standard size:"></qds-label>
    <qds-radio inline checked text="I am selected"></qds-radio>
  </div>
  <div class="qds-controls-large qds-related flex flex-row">
    <qds-label inline size="large" text="Large size:"></qds-label>
    <qds-radio inline checked size="large" text="I am selected"></qds-radio>
  </div>
  <div class="qds-controls-small qds-related flex flex-row">
    <qds-label inline size="small" text="Small size:"></qds-label>
    <qds-radio inline checked size="small" text="I am selected"></qds-radio>
  </div>
</div>

Layout​

Stacking​

Lay out your radios vertically, using the related controls spacing amount between them, and add a <qds-label> to introduce the group:

Loading...
Live Editor
<div class="qds-controls qds-related">
  <qds-label required text="Choose an option:"></qds-label>
  <qds-radio name="stacking-demo" checked text="Option 1"></qds-radio>
  <qds-radio name="stacking-demo" text="Option 2"></qds-radio>
  <qds-radio name="stacking-demo" text="Option 3"></qds-radio>
</div>

Visually present groups of choices as groups and clearly separate them from other groups on the same page:

Loading...
Live Editor
<div class="qds-controls">
  <div class="qds-controls qds-related">
    <qds-label inline text="Your favorite ice cream flavor:"></qds-label>
    <qds-radio name="ice-cream-flavor" checked text="Chocolate"></qds-radio>
    <qds-radio name="ice-cream-flavor" text="Coconut"></qds-radio>
    <qds-radio name="ice-cream-flavor" text="Mint"></qds-radio>
    <qds-radio name="ice-cream-flavor" text="Strawberry"></qds-radio>
    <qds-radio name="ice-cream-flavor" text="Vanilla"></qds-radio>
  </div>
  <div class="qds-controls qds-related">
    <qds-label inline text="Your favorite vegetable:"></qds-label>
    <qds-radio name="vegetable" checked text="Bean"></qds-radio>
    <qds-radio name="vegetable" text="Tomato"></qds-radio>
    <qds-radio name="vegetable" text="Spinach"></qds-radio>
  </div>
</div>

Inlining​

Avoid displaying several radios on the same line.

Set the inline attribute to let the radio's label align nicely with siblings' labels. This is useful for the "Other:" option in a group of radio buttons:

Loading...
Live Editor
<div class="qds-controls qds-related">
  <qds-label inline text="Your favorite vegetable:"></qds-label>
  <qds-radio name="vegetable" checked text="Bean"></qds-radio>
  <qds-radio name="vegetable" text="Tomato"></qds-radio>
  <qds-radio name="vegetable" text="Spinach"></qds-radio>
  <div class="qds-controls qds-related flex-row">
    <qds-radio inline name="vegetable" text="Other:"></qds-radio>
    <qds-input></qds-input>
  </div>
</div>

Note: to keep it simple, the example above does not include the interactions related to the "Other" text field. Don't forget to add them in your product.

In forms​

Follow the Forms design pattern guidelines to properly organize and space your form labels and controls.

Implementation tips​

Importing​

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

To import this component from the public jsDeliver CDN using a JavaScript import:

import { defineCustomElementQdsRadio } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsRadio()

Component reference​

Properties​

Attribute / PropertyTypeDescriptionDefault
checked
boolean | undefined

Sets the radio button's state.

undefined
disabled
boolean | undefined

Prevents the radio button from being interacted with: it cannot be pressed or focused.

undefined
form
string | undefined

The <form> element to associate the radio button with (its form owner).

The value of this property must be the id of a <form> in the same document. If this property is not set, the <qds-radio> is associated with its ancestor <form> element, if any.

This property lets you associate <qds-radio> elements to <form>s anywhere in the document, not just inside a <form>. It can also override an ancestor <form> element.

undefined
inline
boolean

Adds vertical margin to the radio for alignment.

This is useful when creating inline layouts so that the first lines have the correct vertical centering.

false
name
string | undefined

Specify the radio group this radio button belongs to.

Once a radio group is established, selecting any radio button in that group automatically deselects any currently-selected radio button in the same group.

undefined
required
boolean | undefined

Specify the group the radio button belongs to as required.

If any radio button in a same-named group of radio buttons has the required attribute, a radio button in that group must be checked, although it doesn't have to be the one with the attribute applied.

undefined
size
"large" | "small" | "standard" | undefined

The radio button's size.

'standard'
text
string | undefined

The radio button's text.

undefined
value
null | number | string | undefined

The value of the radio button, submitted as a name/value pair with form data.

undefined

Events​

EventTypeDescriptionBubblesCancelableComposedqdsBlur
{ readonly relatedTarget: EventTarget | null; }

Emitted when the radio button loses focus.

qdsChange
void

Emitted when the radio button is checked by the user.

qdsFocus
{ readonly relatedTarget: EventTarget | null; }

Emitted when the radio button gains focus.

Last updated on