Radio

An input of type "radio" is a form element that allows users to select a single item from a list of related options.

Usage

When to use

• To allow users to select a single option from a group of two or more mutually exclusive options.

When not to use

• When users should check and uncheck an option, consider Checkbox.
• When users need to select more than one option from a list, consider Checkbox.
• When checking or unchecking results in an immediate change, consider Toggle.

Layout

We recommend using vertical Radio groups, especially with short option lists.

Required and optional

Generally, we recommend pre-selecting one of the radio buttons by default. However, there could be cases where the default selection could affect the user’s choice (the power of suggestion), and leaving all radio buttons unselected may provide a better user experience. Use required and optional indicators in those instances.

For complex forms, indicate required fields. This is the most explicit and transparent method and ensures users don’t have to make assumptions. Read more about best practices for marking required fields in forms.

For shorter, simpler forms (e.g., login/signup and feedback requests), indicate optional fields instead.

Error validation

For error validation recommendations, refer to the Form patterns documentation.

Content

For general content recommendations, refer to the Primitives documentation.

Related

• Checkbox
• Toggle
• Form patterns

How to use this component

There are three ways to use the Radio component:

• Form::Radio::Base - the base component: the <input> control
• Form::Radio::Field - the field component: the <input> control, with label, helper text, and error messaging (in a wrapping container)
• Form::Radio::Group - the group component: a <legend> (optional), a list of fields, and error messaging

Form::Radio::Group

The basic invocation creates:

• a <fieldset> container.
• a <legend> element.
• a list of rendered <Form::Radio::Field> components.

The @name argument offers an easy way to provide the same name for all the Radio controls in a single place.

<Hds::Form::Radio::Group @name="datacenter" as |G|>
  <G.Legend>Choose datacenter</G.Legend>
  <G.Radio::Field as |F|>
    <F.Label>NYC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>DC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>NYC2</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>SF1</F.Label>
  </G.Radio::Field>
</Hds::Form::Radio::Group>

Layout

To better fit your spacing requirements, choose between two different layout orientations: vertical or horizontal.

<Hds::Form::Radio::Group @name="datacenter-demo2" as |G|>
  <G.Legend>Choose datacenter</G.Legend>
  <G.Radio::Field as |F|>
    <F.Label>NYC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>DC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>NYC2</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>SF1</F.Label>
  </G.Radio::Field>
</Hds::Form::Radio::Group>

<Hds::Form::Radio::Group @layout="horizontal" @name="datacenter-demo2" as |G|>
  <G.Legend>Choose datacenter</G.Legend>
  <G.Radio::Field as |F|>
    <F.Label>NYC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>DC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>NYC2</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>SF1</F.Label>
  </G.Radio::Field>
</Hds::Form::Radio::Group>

Extra content in legend and helper text

The Legend and HelperText contextual components used in the Group yield their content. This means you can also pass structured content.

When helper text is added, the component automatically adds an aria-describedby attribute to the fieldset, associating it with the automatically generated ID.

<Hds::Form::Radio::Group @layout="horizontal" @name="method-demo1" as |G|>
  <G.Legend>Method <Hds::Badge @size="small" @text="Beta" @color="highlight" /></G.Legend>
  <G.HelperText>Choose which HTTP method to use for the communication channel. See <Hds::Link::Inline @href="#">HTTP protocol</Hds::Link::Inline> for more details.</G.HelperText>
  <G.Radio::Field as |F|>
    <F.Label>POST</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>GET</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>PUT</F.Label>
  </G.Radio::Field>
</Hds::Form::Radio::Group>

Required vs. optional

Use the @isRequired and @isOptional arguments to add a visual indication that the field is “required” or “optional”.

<Hds::Form::Radio::Group @isRequired={{true}} @layout="horizontal" @name="method-demo2" as |G|>
  <G.Legend>Method</G.Legend>
  <G.HelperText>Choose which HTTP method to use for the communication channel.</G.HelperText>
  <G.Radio::Field as |F|><F.Label>POST</F.Label></G.Radio::Field>
  <G.Radio::Field as |F|><F.Label>GET</F.Label></G.Radio::Field>
  <G.Radio::Field as |F|><F.Label>PUT</F.Label></G.Radio::Field>
</Hds::Form::Radio::Group>
<br />
<Hds::Form::Radio::Group @isOptional={{true}} @layout="horizontal" @name="method-demo3" as |G|>
  <G.Legend>Method</G.Legend>
  <G.HelperText>Choose which HTTP method to use for the communication channel.</G.HelperText>
  <G.Radio::Field as |F|><F.Label>POST</F.Label></G.Radio::Field>
  <G.Radio::Field as |F|><F.Label>GET</F.Label></G.Radio::Field>
  <G.Radio::Field as |F|><F.Label>PUT</F.Label></G.Radio::Field>
</Hds::Form::Radio::Group>

Validation

To indicate a field is invalid, provide an error message using the Error contextual component.

<Hds::Form::Radio::Group @layout="horizontal" @name="datacenter-demo4" as |G|>
  <G.Legend>Choose datacenter</G.Legend>
  <G.Radio::Field as |F|>
    <F.Label>NYC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>DC1</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>NYC2</F.Label>
  </G.Radio::Field>
  <G.Radio::Field as |F|>
    <F.Label>SF1</F.Label>
  </G.Radio::Field>
  <G.Error>Error: you need to choose one datacenter.</G.Error>
</Hds::Form::Radio::Group>

Field items

A group of Radios is made of one or more Form::Radio::Field components. All the arguments, attributes, and modifiers that can be passed to Form::Radio::Field can be passed to the same items in the Group declaration.

<Hds::Form::Radio::Group @layout="vertical" @name="datacenter-demo5" as |G|>
  <G.Legend>Choose datacenter</G.Legend>
  <G.Radio::Field @id="datacenter-NYC1" checked @value="NYC1" {{on "change" this.yourOnChangeFunction}} as |F|>
    <F.Label>NYC1</F.Label>
    <F.HelperText>CoreSite- 32 Avenue of the Americas</F.HelperText>
  </G.Radio::Field>
  <G.Radio::Field @id="datacenter-DC1" @value="DC1" {{on "change" this.yourOnChangeFunction}} as |F|>
    <F.Label>DC1</F.Label>
    <F.HelperText>CoreSite- K Street</F.HelperText>
  </G.Radio::Field>
  <G.Radio::Field @id="datacenter-NYC2" @value="NYC2" {{on "change" this.yourOnChangeFunction}} as |F|>
    <F.Label>NYC1</F.Label>
    <F.HelperText>H5 Data Center - 325 Hudson Street</F.HelperText>
  </G.Radio::Field>
  <G.Radio::Field @id="datacenter-SF1" @value="SF1" {{on "change" this.yourOnChangeFunction}} as |F|>
    <F.Label>SF1</F.Label>
    <F.HelperText>INAP - 650 Townsend Street</F.HelperText>
  </G.Radio::Field>
</Hds::Form::Radio::Group>

Form::Radio::Field and Form::Radio::Base

The Base and Field components are intended for rare cases where the Group component can’t be used and a custom implementation is needed. Most of the details for the Field component also apply to the Base component, but see the Component API for more details.

The basic invocation for a Field component creates:

• a <label> element with a for attribute automatically associated with the input ID attribute.
• a <input type="radio"> control with an automatically generated ID attribute.

<Hds::Form::Radio::Field name="data-center" @value="SF1" {{on "change" this.yourOnChangeFunction}} as |F|>
  <F.Label>SF1</F.Label>
</Hds::Form::Radio::Field>

The basic invocation for a Base component creates an <input type="radio"> control with an automatically generated ID attribute.

<Hds::Form::Radio::Base
  name="data-center"
  aria-label="San Francisco datacenter number 1"
  @value="SF1"
  {{on "change" this.yourOnChangeFunction}}
/>

Component API

The Radio component has three different variants with their own APIs:

• Form::Radio::Group - the group component: a <legend> (optional), a list of fields, and error messaging
• Form::Radio::Field - the field component: the <input> control, with label, helper text, and error messaging (in a wrapping container)
• Form::Radio::Base - the base component: the <input> control

Form::Radio::Group

Contextual components

Legend, group of Form::Radio::Field components, and Error content are passed to the group as yielded components. The group of elements is automatically wrapped in a <fieldset> element.

Form::Radio::Field

Contextual components

Label, HelperText, and Error content are passed to the field as yielded components.

Form::Radio::Base

Anatomy

Form::Radio::Field

Form::Radio::Group

States

Conformance rating

Form::Radio::Group

Form::Radio::Group is conformant when used as directed.

Form::Radio::Field

Form::Radio::Field is conformant when used as directed.

Form::Radio::Base

Form::Radio::Base is not conformant until it has an accessible name.

Applicable WCAG Success Criteria

This section is for reference only, some descriptions have been truncated for brevity.

This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.