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.
How to use this component
There are three ways to use the Radio component:
Form::Radio::Base- the base component: the<input>controlForm::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-demo1" as |G|>
<G.Legend>Choose datacenter</G.Legend>
<G.RadioField as |F|>
<F.Label>NYC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>DC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>NYC2</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>SF1</F.Label>
</G.RadioField>
</Hds::Form::Radio::Group>Layout
To better fit your spacing requirements, choose between two different layout orientations: vertical or horizontal.
<Hds::Form as |FORM|>
<FORM.Section>
<Hds::Form::Radio::Group @name="datacenter-demo2" as |G|>
<G.Legend>Choose datacenter</G.Legend>
<G.RadioField as |F|>
<F.Label>NYC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>DC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>NYC2</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>SF1</F.Label>
</G.RadioField>
</Hds::Form::Radio::Group>
</FORM.Section>
<FORM.Section>
<Hds::Form::Radio::Group @layout="horizontal" @name="datacenter-demo3" as |G|>
<G.Legend>Choose datacenter</G.Legend>
<G.RadioField as |F|>
<F.Label>NYC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>DC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>NYC2</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>SF1</F.Label>
</G.RadioField>
</Hds::Form::Radio::Group>
</FORM.Section>
</Hds::Form>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.RadioField as |F|>
<F.Label>POST</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>GET</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>PUT</F.Label>
</G.RadioField>
</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 as |FORM|>
<FORM.Section>
<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.RadioField as |F|><F.Label>POST</F.Label></G.RadioField>
<G.RadioField as |F|><F.Label>GET</F.Label></G.RadioField>
<G.RadioField as |F|><F.Label>PUT</F.Label></G.RadioField>
</Hds::Form::Radio::Group>
<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.RadioField as |F|><F.Label>POST</F.Label></G.RadioField>
<G.RadioField as |F|><F.Label>GET</F.Label></G.RadioField>
<G.RadioField as |F|><F.Label>PUT</F.Label></G.RadioField>
</Hds::Form::Radio::Group>
</FORM.Section>
</Hds::Form>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.RadioField as |F|>
<F.Label>NYC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>DC1</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>NYC2</F.Label>
</G.RadioField>
<G.RadioField as |F|>
<F.Label>SF1</F.Label>
</G.RadioField>
<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.RadioField @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.RadioField>
<G.RadioField @id="datacenter-DC1" @value="DC1" {{on "change" this.yourOnChangeFunction}} as |F|>
<F.Label>DC1</F.Label>
<F.HelperText>CoreSite- K Street</F.HelperText>
</G.RadioField>
<G.RadioField @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.RadioField>
<G.RadioField @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.RadioField>
</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 aforattribute automatically associated with the inputIDattribute. - a
<input type="radio">control with an automatically generatedIDattribute.
<Hds::Form::Radio::Field name="data-center-radio" @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.