Skip to main content

Fieldset

A fieldset groups multiple options or form fields together under one question.

The Fieldset component is a group containing multiple form elements such as checkboxes, radio buttons, inputs, textareas, or selects. It is an important semantic that helps screen readers understand the relationship between a meaningful label and the many form elements associated with it. Fieldsets appear similar to the Form group component, however, they are used for different input types and may even contain form group components.

Details

  • Honeycrisp: Form group molecule
  • Customization: Design tokens and Styles
  • Modifier: .cfa-legend, .cfa-hint, .cfa-checkbox, .cfa-radio

The Fieldset includes the checkbox component, radio button component, and other components that do not have dedicated documentation in the USWDS (labels and hints). The visual appearance is modified using design tokens from the Honeycrisp Form elements atom and Form group molecule. Further customization is applied using the CSS modifiers .cfa-legend, .cfa-hint, .cfa-checkbox, .cfa-radio to add styles defined in custom stylesheets.

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

Fieldset with checkbox options.
Do any of the following situations apply to you?
Please check all that apply.

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.

<fieldset class="usa-fieldset cfa-fieldset">
  <legend class="usa-legend cfa-legend">
    <span>Do any of the following situations apply to you?</span>
  </legend>
  <div class="usa-hint cfa-hint" id="hint-e4221d8b08c97">Please check all that apply.</div>
  <div class="usa-checkbox cfa-checkbox">
    <input type="checkbox" id="checkbox-7076308c6fe08" name="checkbox['e4221d8b08c97']" value="in-foster-care" class="usa-checkbox__input usa-checkbox__input--tile">
    <label for="checkbox-7076308c6fe08" class="usa-checkbox__label">
      <span>In foster care</span>
    </label>
  </div>
  <div class="usa-checkbox cfa-checkbox">
    <input type="checkbox" id="checkbox-50df7989163d7" name="checkbox['e4221d8b08c97']" value="unhoused-homeless" class="usa-checkbox__input usa-checkbox__input--tile">
    <label for="checkbox-50df7989163d7" class="usa-checkbox__label">
      <span>Unhoused/homeless</span>
    </label>
  </div>
  <div class="usa-checkbox cfa-checkbox">
    <input type="checkbox" id="checkbox-d8f809f0a2a16" name="checkbox['e4221d8b08c97']" value="child-of-migrant-worker" class="usa-checkbox__input usa-checkbox__input--tile">
    <label for="checkbox-d8f809f0a2a16" class="usa-checkbox__label">
      <span>Child of migrant worker</span>
    </label>
  </div>
  <div class="usa-checkbox cfa-checkbox">
    <input type="checkbox" id="checkbox-bdbcec6b37b06" name="checkbox['e4221d8b08c97']" value="runaway-from-home" class="usa-checkbox__input usa-checkbox__input--tile">
    <label for="checkbox-bdbcec6b37b06" class="usa-checkbox__label">
      <span>Runaway from home</span>
    </label>
  </div>
</fieldset>

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.

{
  "modifier": "cfa-fieldset",
  "legend": {
    "text": "Do any of the following situations apply to you?",
    "modifier": "cfa-legend",
    "modifierHint": "cfa-hint"
  },
  "hint": {
    "text": "Please check all that apply.",
    "modifier": "cfa-hint",
    "id": "hint-e4221d8b08c97"
  },
  "options": [
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-7076308c6fe08",
      "name": "checkbox['e4221d8b08c97']",
      "type": "checkbox",
      "value": "in-foster-care",
      "label": "In foster care",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    },
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-50df7989163d7",
      "name": "checkbox['e4221d8b08c97']",
      "type": "checkbox",
      "value": "unhoused-homeless",
      "label": "Unhoused/homeless",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    },
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-d8f809f0a2a16",
      "name": "checkbox['e4221d8b08c97']",
      "type": "checkbox",
      "value": "child-of-migrant-worker",
      "label": "Child of migrant worker",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    },
    {
      "modifier": "cfa-checkbox",
      "id": "checkbox-bdbcec6b37b06",
      "name": "checkbox['e4221d8b08c97']",
      "type": "checkbox",
      "value": "runaway-from-home",
      "label": "Runaway from home",
      "input": {
        "modifier": "usa-checkbox__input--tile"
      }
    }
  ]
}
Fieldset with radio options.
What type of school are you enrolled in?
Please choose one of the following.

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.

<fieldset class="usa-fieldset cfa-fieldset">
  <legend class="usa-legend cfa-legend">
    <span>What type of school are you enrolled in?</span>
  </legend>
  <div class="usa-hint cfa-hint" id="hint-6b36c90ab8756">Please choose one of the following.</div>
  <div class="usa-radio cfa-radio">
    <input type="radio" id="radio-c75bfa94b4ef5" name="radio['6b36c90ab8756']" value="virtual-school" class="usa-radio__input usa-radio__input--tile">
    <label for="radio-c75bfa94b4ef5" class="usa-radio__label">
      <span>Virtual school</span>
    </label>
  </div>
  <div class="usa-radio cfa-radio">
    <input type="radio" id="radio-6bfb318f2ca82" name="radio['6b36c90ab8756']" value="homeschool" class="usa-radio__input usa-radio__input--tile">
    <label for="radio-6bfb318f2ca82" class="usa-radio__label">
      <span>Homeschool</span>
    </label>
  </div>
</fieldset>

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.

{
  "modifier": "cfa-fieldset",
  "legend": {
    "text": "What type of school are you enrolled in?",
    "modifier": "cfa-legend",
    "modifierHint": "cfa-hint"
  },
  "hint": {
    "text": "Please choose one of the following.",
    "modifier": "cfa-hint",
    "id": "hint-6b36c90ab8756"
  },
  "options": [
    {
      "modifier": "cfa-radio",
      "id": "radio-c75bfa94b4ef5",
      "name": "radio['6b36c90ab8756']",
      "type": "radio",
      "value": "virtual-school",
      "label": "Virtual school",
      "input": {
        "modifier": "usa-radio__input--tile"
      }
    },
    {
      "modifier": "cfa-radio",
      "id": "radio-6bfb318f2ca82",
      "name": "radio['6b36c90ab8756']",
      "type": "radio",
      "value": "homeschool",
      "label": "Homeschool",
      "input": {
        "modifier": "usa-radio__input--tile"
      }
    }
  ]
}
Fieldset with radio options.
Please confirm your address.
We updated the address you entered. If correct, please use the suggested address.

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.

<fieldset class="usa-fieldset cfa-fieldset">
  <legend class="usa-legend cfa-legend">
    <span>Please confirm your address.</span>
  </legend>
  <div class="usa-hint cfa-hint" id="hint-a14177f93e74a">We updated the address you entered. If correct, please use the suggested address.</div>
  <div class="usa-radio cfa-radio">
    <input type="radio" id="radio-ae6049b988649" name="radio['a14177f93e74a']" value="suggested-address" checked="true" class="usa-radio__input usa-radio__input--tile">
    <label for="radio-ae6049b988649" class="usa-radio__label">
      <span>Suggested address</span>
      <span class="usa-radio__label-description">4918 Webster St., Apt 2
        <br> Oakland, CA
        <br> 94609
      </span>
    </label>
  </div>
  <div class="usa-radio cfa-radio">
    <input type="radio" id="radio-13d3c639e5ff8" name="radio['a14177f93e74a']" value="address-you-entered" class="usa-radio__input usa-radio__input--tile">
    <label for="radio-13d3c639e5ff8" class="usa-radio__label">
      <span>Address you entered</span>
      <span class="usa-radio__label-description">4918 Webster Street
        <br> Apt 2
        <br> Oakland, CA
        <br> 94609
      </span>
    </label>
  </div>
</fieldset>

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.

{
  "modifier": "cfa-fieldset",
  "legend": {
    "text": "Please confirm your address.",
    "modifier": "cfa-legend",
    "modifierHint": "cfa-hint"
  },
  "hint": {
    "text": "We updated the address you entered. If correct, please use the suggested address.",
    "modifier": "cfa-hint",
    "id": "hint-a14177f93e74a"
  },
  "options": [
    {
      "modifier": "cfa-radio",
      "id": "radio-ae6049b988649",
      "name": "radio['a14177f93e74a']",
      "type": "radio",
      "value": "suggested-address",
      "label": "Suggested address",
      "description": "4918 Webster St., Apt 2 <br> Oakland, CA <br> 94609",
      "checked": "true",
      "input": {
        "modifier": "usa-radio__input--tile"
      }
    },
    {
      "modifier": "cfa-radio",
      "id": "radio-13d3c639e5ff8",
      "name": "radio['a14177f93e74a']",
      "type": "radio",
      "value": "address-you-entered",
      "label": "Address you entered",
      "description": "4918 Webster Street <br> Apt 2 <br> Oakland, CA <br> 94609",
      "input": {
        "modifier": "usa-radio__input--tile"
      }
    }
  ]
}

Guidance

Fieldsets vs. form groups. Form questions with multiple form elements, such as multi-part text inputs, checkboxes, or radio buttons, may use the fieldset component to group themselves with a single question (or legend element). Use the form group component to associate one form element with one question, such as a text input, text area, or select.

Checkbox options. Refer to checkbox documentation.

Radio button options. Refer to radio button documentation.

Memorable date. Refer to memorable date documentation.

Accessibility

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

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

Checklist Key

  • Passes
    Passes
  • Unchecked
    Unchecked

Design library component

Source and usage

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

  • Sass stylesheet: ./_cfa-fieldset.scss
  • Thymeleaf template fragment: ./cfa-fieldset.th.html
  • Embedded Ruby (ERB) partial template: ./_cfa-fieldset.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-error-dark: 'orange-warm-60v' // Affects the error state border color
);
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.

<fieldset th:fragment="fieldset(modifier, id, legend, required, hint, error, options)" class="usa-fieldset" th:classappend="${modifier}" th:attr="id=${id}">
  <legend class="usa-legend" th:classappend="${legend.modifier}" th:attr="id=${legend.id},tabindex=${legend.tabindex}">
    <span th:utext="${legend.text}">Legend</span>
    <abbr th:if="${required}" aria-hidden="true" class="usa-hint usa-hint--required" th:classappend="${legend.modifierHint}">*</abbr>
  </legend>
  <div th:if="${hint}" class="usa-hint" th:classappend="${hint.modifier}" th:attr="id=${hint.id}" th:utext="${hint.text}">Hint</div>
  <span th:if="${error}" class="usa-error-message" th:classappend="${error.modifier}" th:attr="id=${error.id},role=${error.role},aria-live=${error.ariaLive}" th:utext="${error.text}">Message</span>
  <th:block th:replace="~{packages/cfa-input-select/cfa-input-select.th :: inputSelect(${options}, ${required})}" />
</fieldset>
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-fieldset/cfa-fieldset.th :: fieldset(${modifier}, ${id}, ${legend}, ${required}, ${hint}, ${error}, ${options})}" />
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.

<fieldset class="usa-fieldset<% if defined?(modifier) %> <%= modifier %><% end %>"
  <% if defined?(id) %> id="<%= id %>"<% end %>>
  <legend class="usa-legend<% if legend['modifier'] %> <%= legend['modifier'] %><% end %>"<% if legend['id'] %> id="<%= legend['id'] %>"<% end %><% if legend['for'] %> for="<%= legend['for'] %>"<% end %><% if legend['tabindex'] %> tabindex="<%= legend['tabindex'] %>"<% end %>>
    <span><%= legend['text'] %></span>
    <% if defined?(required) %><abbr aria-hidden="true" class="usa-hint usa-hint--required<% if legend['modifierHint'] %> <%= legend['modifierHint'] %><% end %>">*</abbr><% end %>
  </legend>
  <% if defined?(hint) %><div class="usa-hint<% if hint['modifier'] %> <%= hint['modifier'] %><% end %>"<% if hint['id'] %> id="<%= hint['id'] %>"<% end %>><%= hint['text'] %></div><% end %>
  <% if defined?(error) %><span class="usa-error-message<% if error['modifier'] %> <%= error['modifier'] %><% end %>"<% if error['id'] %> id="<%= error['id'] %>"<% end %><% if error['role'] %> role="<%= error['role'] %>"<% end %><% if error['ariaLive'] %> aria-live="<%= error['ariaLive'] %>"<% end %>><%= error['text'] %></span><% end %>
  <% if defined?(options) %>
    <%= ERB.new(File.read('packages/cfa-input-select/_cfa-input-select.html.erb'), 0, 0, '@inputSelect').result_with_hash({options: options, required: (required if defined?(required)) }.compact) %>
  <% end %>
</fieldset>
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-fieldset/_cfa-fieldset.html.erb'), 0, 0, '@fieldset').result_with_hash({modifier: modifier, id: id, legend: legend, hint: hint, error: error, required: required, options: options}) %>

uswds.codeforamerica.org

Learn more about Code for America by visiting codeforamerica.org