Skip to main content

An official website of the United States government

Here's how you know

An official website of the United States government

Here's how you know


Form Label & Legend

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


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




See Storybook for React guidance of this component.


The following CSS variables can be overridden to customize Form components:

CSS variables for form
VariableDefault Core Theme Value
--form-label__color--inversehex value: #ffffff--color-white
--form-hint__colorhex value: #5a5a5a--color-gray-dark
--form-hint__color--inversehex value: #e9ecf1--color-muted-inverse
--form-error__colorhex value: #e31c3d--color-error
--form-error__color--inversehex value: #f7bbc5--color-error-lighter


Form legend

  • 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.
  • Avoid links in legends when possible. Links inside legends are not read by some screen readers, namely 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.

Form label

  • Each form field should have a <label>. Never use a field's placeholder attribute as the primary way to label the field.
  • Each form field should have a clear, brief, and descriptive label.
  • 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.
  • Don't use a field's placeholder attribute as the primary way to label the field.


  • Describe what the user needs to do when the field is selected
  • Use a phrase or complete sentence
  • Start with an action verb and pair it with a noun to help it be clearer. Example: Enter your age.
  • Use the fewest words possible (i.e. don't use "please")
  • Use sentence case
  • Be consistent with punctuation at the end of a phrase or sentence
  • Be consistent with phrase and sentence structure

Hint text

  • Place hint text within the field's <label> element.
  • Place hint text where appropriate depending on what content it's helping to explain
  • Use hint text for supporting contextual help, which will always be shown.
  • Hint text should sit between a form label and the input.
  • Use lower visual style (i.e., lighter gray than the form label or the input option) so it won't compete for users' attention with the field label.
  • Use hint text to indicate which inputs are optional when there are more required fields than optional.
  • Hint text can also appear after an input box when the text is being used to show the value someone should be entering in the field (e.g., income amount input box displays text after the input box to highlight the amount should be "monthly income".)


  • Use when appropriate to support a form label (Goes below the form label in a lighter weight font)
  • Describe how to best answer the question/form label
  • Use the fewest words possible (i.e. don't use "please")
  • Use sentence case
  • End with a period

Learn More

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.


  • Color

    Meets AA color contrast standards for accessibility and color blindness.
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Not applicable


  • Storybook

    Component has stories to cover all defined props.
  • Responsive

    Component designed to work in all responsive breakpoints.
  • Spanish translations

    Includes Spanish translations for default text content.


  • Code

    Tokens implemented in code.
  • Design

    Tokens implemented in the Sketch.