Select

A Select is a form element that provides users with a way to select amongst a set of options.

Usage

When to use

• As a form element that allows the user to make a selection from a pre-defined set of options.

When not to use

• When a user can select more than one option, consider Checkbox.
• When there are fewer than 5 options, consider Radio.
• To display a list of buttons or links in a menu, consider Dropdown.

Required and optional

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.

If the field is required, consider adding a default value to help the user avoid an error.

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.

Option list

• We recommend keeping options clear and concise; avoid full sentences.

• Avoid using the same word at the beginning of a set of options.

• Order the set of options in a logical way based on the use case. For example:

  • default or most commonly selected options first
  • alphabetically
  • numerically

Related

• Form patterns

How to use this component

There are two ways to use the Select component:

• Form::Select::Base - the base component: just the <select> control.
• Form::Select::Field - the field parent component: the <select> control, with label, helper text, and error messaging (in a wrapping container).

We recommend using the Field component as it provides built-in accessibility functionality. Use the Base component if needing to achieve custom layouts or for special use cases not covered by the Field component.

Form::Select::Field

The basic invocation requires a Label. This creates:

• a <label> element with a for attribute automatically associated with the select ID attribute.
• a <select> control with an automatically generated ID attribute, and the Options elements yielded as children.

<Hds::Form::Select::Field as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Selected option

Pass the native selected attribute to pre-select one of the options.

<Hds::Form::Select::Field as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other" selected>Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Grouped options

To group similar sets of options, use the <optgroup> tag within the Options container.

<Hds::Form::Select::Field as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.Options>
    <optgroup label="Most common">
      <option value="Kubernetes">Kubernetes</option>
      <option value="AWS">AWS</option>
    </optgroup>
    <optgroup label="Others">
      <option value="CloudWise" selected>CloudWise</option>
      <option value="SWA">SWA</option>
      <option value="Other">Other</option>
    </optgroup>
  </F.Options>
</Hds::Form::Select::Field>

Helper text

You can add extra information to the field using helper text. When helper text is added, the component automatically adds an aria-describedby attribute to the select control, associating it with the automatically generated ID of the helper text element.

<Hds::Form::Select::Field @value="036140285924" as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.HelperText>The target infrastructure is where you want to deploy your apps.</F.HelperText>
  <F.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Extra content in label and helper text

The Label and HelperText contextual components used in the Field component yield their content. This means you can also pass structured content.

For example:

<Hds::Form::Select::Field as |F|>
  <F.Label>Target infrastructure <Hds::Badge @size="small" @text="Beta" /></F.Label>
  <F.HelperText>This is an experimental feature (<Hds::Link::Inline @href="#">read more</Hds::Link::Inline>).</F.HelperText>
  <F.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Required vs. optional

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

<Hds::Form::Select::Field @isRequired={{true}} as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.HelperText>The target infrastructure is where you want to deploy your apps.</F.HelperText>
  <F.Options>
    <option value=""></option>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>
<br />
<Hds::Form::Select::Field @isOptional={{true}} as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.HelperText>The target infrastructure is where you want to deploy your apps.</F.HelperText>
  <F.Options>
    <option value=""></option>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Validation

To indicate a field is invalid, declare that it’s invalid by using the @isInvalid argument and provide an error message using the Error contextual component.

<Hds::Form::Select::Field @isInvalid={{true}} as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.HelperText>The target infrastructure is where you want to deploy your apps.</F.HelperText>
  <F.Options>
    <option value=""></option>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
  <F.Error>Error: select one of the options.</F.Error>
</Hds::Form::Select::Field>

Custom control ID

If needing a custom ID for the control instead of the one automatically generated by the component, pass the @id argument to the field.

<Hds::Form::Select::Field @id="my-control" as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.HelperText>The target infrastructure is where you want to deploy your apps.</F.HelperText>
  <F.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Additional aria-describedby

Pass an @extraAriaDescribedBy argument to the field to connect one or more extra elements describing the field to the control. This provides extra ID values to the aria-describedby attribute of the control, in addition to those automatically generated by the component.

<Hds::Form::Select::Field @extraAriaDescribedBy="my-extra-element-ID" as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.HelperText>The target infrastructure is where you want to deploy your apps.</F.HelperText>
  <F.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Native HTML attributes

This component supports use of ...attributes. This means you can use all the standard HTML attributes of the <select> element. This can be useful in case you want to add specific native behaviors to the field, that are not exposed directly by the component (e.g., providing a name for the control, or adding multiple and size attributes to it).

Similarly, you can pass HTML attributes to the <option/optgroup> elements.

<Hds::Form::Select::Field name="infrastructure" multiple size="8" as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.Options>
    <optgroup label="Most common">
      <option value="Kubernetes">Kubernetes</option>
      <option value="AWS">AWS</option>
      <option value="Azure" disabled>Azure</option>
    </optgroup>
    <optgroup label="Others">
      <option value="Alibaba" selected>Alibaba</option>
      <option value="CloudWise" selected>CloudWise</option>
      <option value="SWA">SWA</option>
      <option value="Other">Other</option>
    </optgroup>
  </F.Options>
</Hds::Form::Select::Field>

Event handling

Because this component supports use of ...attributes, you can use all the usual Ember techniques for event handling (e.g., blue, change), validation, etc.

<Hds::Form::Select::Field {{on "blur" this.yourOnBlurFunction}} as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.Options>
    <option value=""></option>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Custom width

By default, the select control width is set to fill the parent container.

Pass a custom width for the control using the @width argument.

<Hds::Form::Select::Field @width="200px" as |F|>
  <F.Label>Target infrastructure</F.Label>
  <F.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </F.Options>
</Hds::Form::Select::Field>

Form::Select::Base

The Base component is intended for rare cases where the Field 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 Base component creates a <select> control with an automatically generated ID attribute.

<Hds::Form::Select::Base aria-label="Target infrastructure" @isRequired={{true}} {{on "blur" this.yourOnBlurFunction}} as |S|>
  <S.Options>
    <option value="Kubernetes">Kubernetes</option>
    <option value="Other">Other</option>
  </S.Options>
</Hds::Form::Select::Base>

Component API

The Select component has two different variants with their own APIs:

• Form::Select::Base - the base component: just the <select> control.
• Form::Select::Field - the field parent component: the <select> control, with label, helper text, and error messaging (in a wrapping container).

Form::Select::Base

Contextual components

The select options are passed to the field as yielded components, using the Options key.

Form::Select::Field

Contextual components

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

Anatomy

States

Conformance

Form::Select::Field

Form::Select::Field is conformant when used as directed. For this reason, we recommend using Form::Select::Field by default.

Form::Select::Base

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

Interactions

Applicable WCAG Success Criteria (Reference)

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.