Components

Label

Use: Deployed

Labels associate a descriptive title with each form input used to collect information from the user.

Examples

Examples shown here use the va-text-input component to demonstrate form labels. Labels are used consistently across standard form components.

Default

View Label default in Storybook

Required

View Label required in Storybook

Usage

When to use label

All form inputs must have a label. All standard form inputs must have an associated label. Thus the label elements is built into our standard form components.

How this component works

Show whether a field is required or optional. Mark required fields using the required property on the web component.

Error handling

View va-text-input with error in Storybook

In all cases, only show error validation messages or stylings after a user has interacted with a particular field.
The form field and its corresponding <label> are wrapped in a container which provides a thick border and padding to visual indicate an error message to users who might have difficulty perceiving contrast. It also changes the border of the input to red as a secondary indicator.
An error message is placed between the label and the form field.
The form field receives an aria-describedby attribute that references the id of the error message.
Prepending <span class="sr-only">Error</span> to error messages alerts screen screen readers clearly that an error exists.

Review the help users to recover from errors pattern

Hint text

When a detailed form input label is not enough to convey the meaning or purpose of the input, we have three options for including additional context:

Beneath the label (default)
Inline within the label
Additional info

Default hint text

View Label with hint text in Storybook

This should be used in the case where the needed clarification is a little longer, but less than two sentences. These should ideally not wrap more than twice for a total of three lines.

Inline within the label

View Label with inline hint text in Storybook

This should be used in the case where the needed clarification is very short.

With Additional info

View Label with additional info hint text in Storybook

Using the additional info component should only be done in cases where the needed clarification is long, complex, requiring more than two sentences or multiple paragraphs, or special formatting (bullet points, links, etc.).

We want to avoid this variation when possible. Use of this component for this purpose is a last resort when attempts at reducing the content have failed. If a field needs a lot of explanation, it should ideally be moved to a distinct page with explanation on the page itself.

Content considerations

Standardized labels by form pattern

We’re in the process of standardizing form field labels and their related hint text and error messages. We’ll add to this list as we build out the set of standardized labels.