Checkbox

Checkboxes let me choose one or more options from a list.

The Checkbox component allows users to choose one or more options from a list on the page in a fieldset. They enable users full control to select and deselect an individual option if they change their mind.

Details

Extends: USWDS Checkbox component
Honeycrisp: Form element atom
Customization: Design tokens and Styles
Modifier: .cfa-checkbox

The Checkbox extends the USWDS Checkbox component. The visual appearance is modified using design tokens applied to the USWDS Checkbox component settings from the Honeycrisp Form element atom. Further customization is applied using the CSS modifier(s) .cfa-checkbox to add styles defined in a custom stylesheet.

Design tokens. Tokens define the name of basic system elements such as color, typography, or spacing. The values of tokens are relative to how the system defines them. This enables teams to alter the visual appearance of components yet remain within the system boundaries. Learn more about tokens on the Bixal's Design Tokens Guide.

Modifier. A modifier is a class name that applies a variant, type, or extended style customization to modify the component's visual appearance.

Examples

Checkboxes

Option A

Option B

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<div class="usa-checkbox cfa-checkbox">
  <input type="checkbox" id="checkbox-e3bc9437d8fcb" name="checkbox['797cd3de8d362']" value="option-a" class="usa-checkbox__input usa-checkbox__input--tile">
  <label for="checkbox-e3bc9437d8fcb" class="usa-checkbox__label">
    <span>Option A</span>
  </label>
</div>
<div class="usa-checkbox cfa-checkbox">
  <input type="checkbox" id="checkbox-13eed1125db74" name="checkbox['797cd3de8d362']" value="option-b" class="usa-checkbox__input usa-checkbox__input--tile">
  <label for="checkbox-13eed1125db74" class="usa-checkbox__label">
    <span>Option B</span>
  </label>
</div>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "options": [
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-e3bc9437d8fcb",
      "name": "checkbox['797cd3de8d362']",
      "type": "checkbox",
      "value": "option-a",
      "label": "Option A",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    },
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-13eed1125db74",
      "name": "checkbox['797cd3de8d362']",
      "type": "checkbox",
      "value": "option-b",
      "label": "Option B",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    }
  ]
}

Checkboxes with descriptions

Option A Option description

Option B Option description

View HTML

<div class="usa-checkbox cfa-checkbox">
  <input type="checkbox" id="checkbox-534260f060f7a" name="checkbox['c13a0d427ed91']" value="option-a" class="usa-checkbox__input usa-checkbox__input--tile">
  <label for="checkbox-534260f060f7a" class="usa-checkbox__label">
    <span>Option A</span>
    <span class="usa-checkbox__label-description">Option description</span>
  </label>
</div>
<div class="usa-checkbox cfa-checkbox">
  <input type="checkbox" id="checkbox-274e996a6d7be" name="checkbox['c13a0d427ed91']" value="option-b" class="usa-checkbox__input usa-checkbox__input--tile">
  <label for="checkbox-274e996a6d7be" class="usa-checkbox__label">
    <span>Option B</span>
    <span class="usa-checkbox__label-description">Option description</span>
  </label>
</div>

View context passed to this component

{
  "options": [
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-534260f060f7a",
      "name": "checkbox['c13a0d427ed91']",
      "type": "checkbox",
      "value": "option-a",
      "label": "Option A",
      "description": "Option description",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    },
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-274e996a6d7be",
      "name": "checkbox['c13a0d427ed91']",
      "type": "checkbox",
      "value": "option-b",
      "label": "Option B",
      "description": "Option description",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    }
  ]
}

Guidance

Fieldsets. Form questions with checkbox components always use the fieldset component to group available options with a visible legend element.

Refer to additional guidance on the USWDS documentation site.

USWDS documentation site

Additional references

Accessibility

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

Refer to additional accessibility guidance on the USWDS documentation site.

Checklist Key

Passes
Unchecked

Design library component

Source and usage

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

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

Packages are collections of functionality that make up a component. Typically, they include stylesheets, templates, and scripts. Learn more about packages on the USWDS documentation site.

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-lightest: 'gray-warm-4', // Affects checkbox and radio hover state
  $cfa-input-select-size: 3,               // Affects checkbox and radio
  $cfa-input-tile-border-radius: 0,        // Affects checkbox and radio
  $cfa-input-tile-border-width: 2px,       // Affects checkbox and radio
  // Component specific settings
  $cfa-checkbox-border-radius: 0
);
// Package-level settings
@use 'cfa-core' with (
  $cfa-input-select-margin: 1.5,  // Affects checkbox and radio
  $cfa-input-select-width: 2,     // Affects checkbox and radio
  $cfa-input-select-height: 2,    // Affects checkbox and radio
  $cfa-input-select-padding-x: 3, // Affects checkbox and radio
  $cfa-input-select-padding-y: 2, // Affects checkbox and radio
  $cfa-input-select-gap: 2        // Affects checkbox and radio
);

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.

<div th:fragment="inputSelect(options, required)" th:each="option: ${options}" th:class="'usa-' + ${option.type} + ' ' + ${option.modifier}">
  <input th:class="'usa-' + ${option.type} + '__input ' + ${option.input.modifier}" th:attr="type=${option.type},id=${option.id},name=${option.name},aria-invalid=${option.ariaInvalid},aria-describedby=${option.ariaDescribedby},value=${option.value},checked=${option.checked},required=${required},data-js=${option.js},data-aria-controls=${option.dataAriaControls}" />
  <label th:class="'usa-' + ${option.type} + '__label'" th:attr="for=${option.id}">
    <span th:if="${option.label}" th:text="${option.label}">Label</span>
    <span th:if="${option.description}" th:class="'usa-' + ${option.type} + '__label-description'" th:utext="${option.description}">Description</span>
  </label>
</div>

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-input-select/cfa-input-select.th :: inputSelect(${options}, ${required})}" />

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.

<% options.each do |option| %>
<div class="usa-<%= option['type'] %><% if option['modifier'] %> <%= option['modifier'] %><% end %>">
  <input class="usa-<%= option['type'] %>__input<% if option['input']['modifier'] %> <%= option['input']['modifier'] %><% end %>"
    <% if option['type'] %> type="<%= option['type'] %>"<% end %>
    <% if option['id'] %> id="<%= option['id'] %>"<% end %>
    <% if option['name'] %> name="<%= option['name'] %>"<% end %>
    <% if option['ariaInvalid'] %> aria-invalid="<%= option['ariaInvalid'] %>"<% end %>
    <% if option['ariaDescribedby'] %> aria-describedby="<%= option['ariaDescribedby'] %>"<% end %>
    <% if option['value'] %> value="<%= option['value'] %>"<% end %>
    <% if option['checked'] %> checked="<%= option['checked'] %>"<% end %>
    <% if defined?(required) %>required<% end %> />
  <label class="usa-<%= option['type'] %>__label"<% if option['id'] %> for="<%= option['id'] %>"<% end %>>
    <% if option['label'] %><span><%= option['label'] %></span><% end %>
    <% if option['description'] %><span class="usa-<%= option['type'] %>__label-description"><%= option['description'] %></span><% end %>
  </label>
</div>
<% end %>

<% options.each do |option| %>
<div class="usa-<%= option['type'] %><% if option['modifier'] %> <%= option['modifier'] %><% end %>">
  <input class="usa-<%= option['type'] %>__input<% if option['input']['modifier'] %> <%= option['input']['modifier'] %><% end %>"
    <% if option['type'] %> type="<%= option['type'] %>"<% end %>
    <% if option['id'] %> id="<%= option['id'] %>"<% end %>
    <% if option['name'] %> name="<%= option['name'] %>"<% end %>
    <% if option['ariaInvalid'] %> aria-invalid="<%= option['ariaInvalid'] %>"<% end %>
    <% if option['ariaDescribedby'] %> aria-describedby="<%= option['ariaDescribedby'] %>"<% end %>
    <% if option['value'] %> value="<%= option['value'] %>"<% end %>
    <% if option['checked'] %> checked="<%= option['checked'] %>"<% end %>
    <% if defined?(required) %>required<% end %> />
  <label class="usa-<%= option['type'] %>__label"<% if option['id'] %> for="<%= option['id'] %>"<% end %>>
    <% if option['label'] %><span><%= option['label'] %></span><% end %>
    <% if option['description'] %><span class="usa-<%= option['type'] %>__label-description"><%= option['description'] %></span><% end %>
  </label>
</div>
<% end %>

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-input-select/_cfa-input-select.html.erb'), 0, 0, '@inputSelect').result_with_hash({required: required, options: options}) %>

Have a suggestion or need help?