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

Theme:

Design system switcher

Version:

Design system switcher

Theme:

Design system switcher

Version:

Design system switcher

Label & Legend

Labels & legends describe individual form fields or fieldsets.

Examples

Loading

Code

React

See Storybook for React guidance of this component.

Web Component

See Storybook for Web Component guidance of this component.

Style customization

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

CSS variables for form
VariableDefault Core Theme Value
--form__max-width460px
--form__max-width--small6em
--form__max-width--medium12em

Guidance

  • Labels/Legends are built into all design-system form fields but can be used on their own to create custom fields.
  • Label/Legend text should be short and in sentence case.
  • Avoid colons at the end of labels and legends.
  • Don't place links or other interactive text in labels or legends. Those should go in the hint text.
  • Don't use a field's placeholder attribute as the primary way to label the field.

Label

  • 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.

Legend

  • Use a single legend for fieldset (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.

Content

  • Use sentence case.
  • Content style for labels varies based on the user experience and its goals.
    • Form fields can use traditional labels for many items. (Examples: "First name," "Last name," "Address," etc.) Traditional labels don’t need punctuation.
    • Form labels and decision helpers can use completes sentences (imperatives or questions) for user understanding or conversational feel. (Examples: "Tell us why you need a faster decision." "Select a reason for your request." "Do you want to see costs when you compare X?" "Do you have another mailing address?") Include punctuation.
  • For imperative labels, 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. Don't use "please" or add unnecessary explanation/context in your label. Instead, use hint text or hint text with a help drawer link to provide information the user must have to correctly enter their answer.

Accessibility testing

General observations

  • Labels should be linked to their corresponding input fields via the for attribute. The for attribute of the label must exactly match the unique id of the related form control.
  • No other interactive elements (such as links or buttons) should be included inside the label.
  • Label text should meet size and contrast requirements.

Screen reader testing

  • When the label's input field gets focus, the label should be read out.

Pointer device testing

  • Clicking the label should focus on its input field.

Learn More

Component maturity

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

Accessibility

  • Color

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

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

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

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

    Component is fully navigable with a keyboard.
    Not applicable

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

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

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete