Form layouts guidelines
This page documents patterns for form layout, validation and how best to use various components.
Key Principles
Help users achieve success
Our form components try to be as informative and clear as possible for the user to avoid errors or confusion.
Use labels and descriptions
Use a label (and description if needed) for each form field. All form fields should be considered required unless stated alongside the label.Provide help text
Show validation parameters in the help text below the input. For example: Spaces and special characters are not allowed.Validate on blur
Validation should occur on blur from an input field. The submit button should be active by default, then show errors after click. Error messages should be specific to the situation.Provide transparency
It should be clear to users what they can accomplish in each part of the form.
Layout matters
A well-formatted layout makes it clear to users how to navigate the form. As one field is completed, it should be clear where to go next.Words matter
Form labels and descriptions are equally important as layout and should be treated with just as much care. The text should be specific, concise, and easy to scan.Maintain a standard layout
Keep the form divided into two columns, with the descriptions on one side and form fields on the other.
Do: To make groupings clearer and keep the user's eye in one path, it's better to keep inputs in a single column. If multiple fields are needed, they should still remain within the column.
Don't: Avoid nesting form rows. It creates an uneven path for the user's eye to travel down the form.
Divide the form into sections
As a form grows longer, it's best to divide the form into sections. This helps the user quickly scan the form and provides visual breaks between multiple input fields.
Do: Adding visual indicators can help clearly define the sections of the form.
Don't: Using panels within panels creates too much visual noise and can make it confusing where sections begin and end.
Do: Add more spacing between form groups than fields within the group to better define the grouping.
Don't: Avoid using the same spacing between groups and individual fields. It is harder for the user to scan and understand the sections of the form.
Described groups
An EuiDescribedFormGroup provides an additional heading along with description text for a single input or set of input fields.
When to use it
This component is not intended for every type of form, but typically works best in the following scenarios.
Forms with lengthy descriptions per input
If a longer description is needed, use an EuiDescribedFormGroup to divide the form into a column for descriptions and a column for form fields. This is so there is space for descriptions to aid new users, but keeps the form fields in a column, so frequent users can still quickly navigate the form. Try to limit the description to three sentences or less.Forms with multiple inputs falling under a single heading
If multiple sub-steps are needed, grouping them together using an EuiDescribedFormGroup helps show they are all still related.Forms with complex nested options
A described group is useful when there are parts of the form that can be hidden and shown by the user. The toggle to hide and show the row should be beneath the description and the following form fields should be in the right column with the other form fields.
Form copy
Labels
Avoid long labels, but don't sacrifice clarity. If needed, put additional information in help text and tooltips.
Do: Say what the field is in the label. Use help text for additional information.
Don't: Put everything in the label. It's hard to scan.
Hint text
Place hints and instructions outside a text field so it is always visible to the user. Keep the hint text short, maximum two sentences long. Use hint text to:
- Explain why you are asking a certain question: "We will only email you if there is a problem with your order."
- Provide clarifying details on what to type: "Enter the full 32-character ID."
- Tell the user where to find the information you're asking for: "Find the Elasticsearch cluster ID on the main administration page of your deployment."
Do: Help users make the right decision by clarifying what goes inside a field.
Do: Use complete sentences and ending punctuation.
Placeholder text
Use the placeholder property to describe the expected value of the input or to provide a useful example.
Do: Provide a simple example that highlights the expected syntax or value.
Don't: Start with `for example`, or `e.g.`.
Add placeholder text in addition to field labels and help text, not as a replacement. Omit it if it doesn't add value for users. And keep it short.
Do: Place info essential to completing the form outside the field so that it is always visible.
Don't: Use text that adds no value, such as “Type here”.
When space is limited and the UI is very simple, you can use field labels as placeholder text. This must stay an exception.
Don't: If space allows it, prefer following the rule described earlier with labels outside of the fields.
In a search bar, be specific about what users can enter.
Do: Give users a hint at things they might want to search for. State the action the user performs (find, search) instead of the field functionality (jump to).
Don't: Use an ellipsis.