Skip to main content

U.S. flagU.S. flag

An official website of the United States government

CMS Design System

CMS Design System v2 is released!  See our migration guide.

Form Label & Legend

Form Labels & Legends are used with form inputs to provide labels, hints, and errors that help the user enter information.

Code snippet
<div class="example--wrapper">
  <label class="ds-c-label" for="number-field-id">
    <span>Phone number</span>
    <span class="ds-c-field__hint">
      Optional. We'll use this number as a backup if we need to contact you about your application.
    </span>
    <span class="ds-c-field__error-message" role="alert">
      Please enter a valid phone number.
    </span>
  </label>
  <div class="example--wrapper example--inverse">
    <label class="ds-c-label" for="inverse-field-id">
      <span>Inverse example</span>
      <span class="ds-c-field__hint ds-c-field__hint--inverse">
        Helpful hint text
      </span>
      <span class="ds-c-field__error-message ds-c-field__error-message--inverse" role="alert">
        Example error message
      </span>
    </label>
  </div>
</div>
React

<FormLabel>

View source file

The FormLabel component provides the label (or legend) for a field, along with any associated hint text and error message.

Code snippet
ReactDOM.render(
  <div className="example--wrapper">
    <FormLabel
      errorMessage="Please enter a valid phone number."
      hint="We'll use this number as a backup if we need to contact you about your application."
      fieldId="number-field-id"
      requirementLabel="Optional"
    >
      Phone number
    </FormLabel>
    <div className="example--wrapper example--inverse">
      <FormLabel
        errorMessage="Example error message"
        hint="Helpful hint text"
        fieldId="inverse-field-id"
        inversed
      >
        Inverse example
      </FormLabel>
    </div>
  </div>,
  document.getElementById('js-example')
);

Props

React Properties Documentation
NameTypeDefaultDescription
children

Required

string, node

Label text or HTML.

classNamestring

Additional classes to be added to the root element.

component'label', 'legend''label'

The root HTML element used to render the label

errorMessagestring, number, element, or array

Enable the error state by providing an error message.

errorMessageClassNamestring

Additional classes to be added to the error message

errorIdstring

The ID of the error message applied to this field.

fieldIdstring

The ID of the field this label is for. This is used for the label's for attribute and any related ARIA attributes, such as for the error message.

hintstring, number, element, or array

Additional hint text to display

idstring

A unique id for the label element. Useful for referencing the label from other components with aria-describedby.

inversedbool

Set to true to apply the "inverse" theme

requirementLabelstring, number, element, or array

Text showing the requirement (ie. "Optional", or "Required"). In most cases, this should be used to indicate which fields are optional. See the form guidelines for more info.

textClassNamestring

Additional classes to be added to the label text.

Guidance

When to use

Labels

  • Each form field should have a <label>. Never use a field's placeholder attribute as the primary way to label the field.

Legends

  • Use a single legend for fieldset (this is required). One example of a common use of fieldset and legend is a question with radio button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the legend tag.

Usage

Labels

  • Apply the .ds-c-label class to <label> elements.
  • Each field should have a <label>. Never use a field's placeholder attribute as the primary way to label the field.
  • Labels should have a for attribute, referencing the corresponding input's unique id attribute. Only one label can be associated to each unique form element.
  • Labels should be placed above their fields.
  • Label text should be short and in sentence case.
  • Avoid colons at the end of labels.

Legends

  • Avoid links in legends when possible. Links inside legends are not read by some screen readers, most notably Internet Explorer 11, paired with JAWS. If you need a pattern like this, put the link outside of the legend element, but keep all other useful hint text in the legend.

Hint text

  • Place hint text within the field's <label> element.
  • Apply the .ds-c-field__hint class to hint text.
  • Use hint text for supporting contextual help, which will always be shown.
  • Hint text should sit above a form field and below the label text.

Validation

  • Place inline validation messages within the field's <label> element.
  • Apply the .ds-c-field__error-message class to error text.
  • Visually align inline validation messages with the input fields, so people using screen magnifiers can read them quickly.
  • Either place an icon next to the error, labeling the icon as error with ARIA or off-screen text, or use text in front of the message itself. Like: "Error: The email address is not a valid email address." The use of the icon or text not only clearly labels the following text as an error, but allows users to know that the message is an error without relying on color alone.
  • The form field receives an aria-describedby attribute that references the id of the error message.
  • The error message should be wrapped in an role="alert" so that screen readers users receive the message, and can act on it. If the page is fully refreshed, add ‘Error: ’ to the beginning of the page <title> so screen readers read it out as soon as possible.

Learn More