---
layout: styleguide
type: component
title: Forms
lead: USAJOBS adds or clarifies design for labels, contextual help, required/optional field handling, and legend.
---
Design Complete
Contextual Help
Contextual help provides assistance in clarifying the intent of a question or form input.
Brief help
Usability
When to use
A concise explanation of the intent of the question or data being requested can be provided without the need for deeper explanation.
As a replacement for placeholder text in order to provide an example of the type of data being requested.
When to consider something else
When a more detailed explanation is needed.
When you want to provide supporting documentation or policy.
Guidance
Help text must not begin with a "-" (dash) or other punctuation.
Detailed Help
Extended help
Outside help - DEPRECATED
Usability
When to use
A detailed explanation of the data being requested is necessary.
Additional context for why the request is being made is desired.
When to consider something else
A more detailed explanation is not necessary.
Dropdown
Our dropdown adds protection from the text running into the dropdown arrow. We also have adopted the select2 plugin for long dropdown menus.
Usability
When to use
Use the chosen plugin when there are more than 25 options in a dropdown.
When to consider something else
When the select menu is 25 items or less use of the chosen plugin is not necessary.
Disabled
Guidance and styling on disabled and readonly inputs and select elements.
Disabled
Labels
Labels are simple text descriptions of data being requested and are found in close proximity to a form input that requests that data.
Usability
Guidance
Labels are concise text that describes the data being requested by a form input.
If all fields are required consider the form legend to communicate that to the user.
Legends
There are two types of legends: Form and fieldset.
.usajobs-form__legend
.usajobs-fieldset legend
Form legend
When to use
When all fields for a form are required use the text "All fields are required".
When all fields for a form are optional use the text "All fields are optional".
When most of the form fields are required use the text "All fields are required unless otherwise noted" in conjunction with the Optional Field Indicator to indicate the optional fields.
When not to use form legend
The form legend may be omitted in cases where the form is extremely short or the fields are obviously required. For example, a form that consists of one checkbox or a sign in form.
Guidance
The form title is often long enough to cause a collision with the legend, thus it was moved to be on the line below the form title.
Fieldset legend
When to use
When multiple fieldsets are in use within a form.
Validation
Styling, timing, and alert style guidance.
Visual
Input boxes and dropdowns in error should be outlined in red.
A vertical red bar should run along the left side of all failed form fields. The red bar should run the length of each individual question, including the radio buttons or answer options.
Input boxes and dropdowns no longer in error should be outlined in green.
When a field is required the help text "This field is required" should be placed directly under the field label or required question.
The help text related to character issues or unmet requirements should use the text "This field" rather than the actual field name.
Timing
Errors
Inline error validation should occur on all required input fields and dropdowns. The error styling should be triggered after the field has lost focus (the user has clicked or tabbed away from the input field without meeting field requirements).
Do not display an alert at the top of the page when using inline error validation.
Inline error validation should also occur if a user enters a character that does not meet the requirements of the field. For example, entering a number in the first name text input. This should occur for optional and required fields.
Success
Success styling should be triggered when a form error (red styling) is corrected. The success validation should appear once the user clicks or tabs out of the input and meets the basic requirements of that field.
Success styling should be removed when the page is saved.
Dependent fields
When you have dependent fields (i.e. Start Date & End date) you should not receive an error on either field until the user leaves the set (both fields). After the set has been left, error styling should be triggered on one or both of the fields.
Error alert
If a user saves a form with known errors or skipped required fields, reload the page with the errors styling displayed and an alert at the top of the page.
The alert should appear above the form but not within the form.
The alert should read "We can’t save your information because there are one or more errors. Please correct the information below and then save your changes."
Alternative Layouts
Horizontal layout
Horizontal layout with validation error -- Left
Horizontal layout with validation error -- Right
Usability
When to use
Use this layout sparingly as the standard error handling was not designed to be used in side-by-side columns. Our only current approved use is in Saved search which is depicted above.
Reveal fields
Selecting certain form elements can reveal additional elements. This allows for hiding complexity from users that don't need to see it.
Reveal hidden form fields
Usability
When to use
Use this pattern to reveal form fields based on user input.