Skip to main content

Select

A select lets me choose one out of many options from a pop-up list.

The Select component allows users to choose one option from a list in a modal dialog. The full list of options is only visible once a user interacts with the select.

Details

Examples

Select

Guidance

Form groups. Form questions with select components always use the form group component to wrap the select with a visible label element.

Refer to additional guidance on the USWDS documentation site.

USWDS documentation site

Additional references

  1. Select | GOV.UK Design System
  2. Select | VA.gov Design System

Accessibility

  • Unchecked
    Customization to the visual appearance of the Select has been verified for WCAG 2.1 AA contrast minimum success.
  • Unchecked
    The Select examples pass manual audits (WCAG 2.1 AA using axe or Lighthouse).
  • Unchecked
    The Select achieves WCAG 2.1 AA resizing success.
    Resizing text up to 200% without loss of content or functionality.
  • Unchecked
    The Select passes keyboard interaction tests.
    No keyboard test has been created.
  • Unchecked
    The Select passes screen reader interaction tests.

  • Unchecked
    Guidance on ensuring Select accessibility has been provided in this documentation.

Refer to additional accessibility guidance on the USWDS documentation site.

Checklist Key

  • Passes
    Passes
  • Unchecked
    Unchecked

Design library component

Source and usage

Package: @codeforamerica/uswds/packages/cfa-select

  • Sass stylesheet: ./_cfa-select.scss
  • Thymeleaf template fragment: ./cfa-select.th.html
  • Embedded Ruby (ERB) partial template: ./_cfa-select.html.erb
Sass theme settings

Below is a demonstration of customizing the component theme settings. Refer to the theme and package-level settings documentation.

// Theme-level settings
@use 'cfa-uswds-theme' with (
  // Global theme settings that affect the component, changing these will affect other components
  $cfa-color-base-ink: 'gray-warm-90' // Affects the text and border color of the select
);
// Package-level settings
@use 'cfa-core' with (
  $cfa-form-elements-border-width: 2px,
  $cfa-form-elements-padding-y: 2,
  $cfa-form-elements-padding-x: 2.5,
  $cfa-select-height: 8
);
USWDS theme settings

Refer to the usage documentation for additional USWDS theme settings.

@use "uswds-core" with ( /* additional USWDS theme settings */ );
Thymeleaf template fragment

This is the pre-rendered template fragment from the package. It is the same template used to render the demonstrations above. You may copy and paste from this example or use the template using the th:block th:replace tag. See the example below.

<select th:fragment="select(selectEl)" class="usa-select" th:classappend="${selectEl.modifier}" th:attr="id=${selectEl.id},name=${selectEl.name},aria-invalid=${selectEl.ariaInvalid},aria-describedby=${selectEl.ariaDescribedby},required=${selectEl.required}">
  <option th:if="${selectEl.default}" th:attr="value=${selectEl.default.value},selected=${selectEl.default.selected}" th:text="${selectEl.default.label}">Label</option>
  <option th:each="option: ${selectEl.options}" th:attr="value=${option.value},selected=${option.selected},disabled=${option.disabled}" th:text="${option.label}">Label</option>
</select>
Template fragment inclusion

Below is an example of how to use the fragment from the package directory using the th:block th:replace inclusion tag. Replace the fragment parameters using your variables or context.

<th:block th:replace="~{packages/cfa-select/cfa-select.th :: select(${selectEl})}" />
ERB template partial

This is the pre-rendered partial template from the package. You may copy and paste from this example or use the template directly from the path.

<select class="usa-select<% if selectEl['modifier'] %> <%= selectEl['modifier'] %><% end %>"
  <% if selectEl['id'] %> id="<%= selectEl['id'] %>"<% end %>
  <% if selectEl['name'] %> name="<%= selectEl['name'] %>"<% end %>
  <% if selectEl['ariaInvalid'] %> aria-invalid="<%= selectEl['ariaInvalid'] %>"<% end %>
  <% if selectEl['ariaDescribedby'] %> aria-describedby="<%= selectEl['ariaDescribedby'] %>"<% end %>
  <% if selectEl['required'] %> required="<%= selectEl['required'] %>"<% end %>>
  <% if selectEl['default'] %><option
    <% if selectEl['default']['value'] %> value="<%= selectEl['default']['value'] %>"<% end %>
    <% if selectEl['default']['selected'] %> selected="<%= selectEl['default']['selected'] %>"<% end %>>
    <%= selectEl['default']['label'] %>
  </option>
  <% end %>
  <% selectEl['options'].each do |option| %>
  <option
    <% if option['value'] %> value="<%= option['value'] %>"<% end %>
    <% if option['selected'] %> selected="<%= option['selected'] %>"<% end %>
    <% if option['disabled'] %> disabled="<%= option['disabled'] %>"<% end %>>
    <%= option['label'] %></option>
  <% end %>
</select>
Partial render

Below is an example of how to include the partial in a view from the package directory using the Ruby ERB class. Replace the argument values using your variables or context. In a Rails environment, the render method can be used instead with the same hash values.

<%= ERB.new(File.read('packages/cfa-select/_cfa-select.html.erb'), 0, 0, '@select').result_with_hash({selectEl: selectEl}) %>

uswds.codeforamerica.org

Learn more about Code for America by visiting codeforamerica.org