Forms in Overlays
Forms often appear in overlays like Dialogs and Drawers, e.g., when creating an entity or editing settings.
This guidance covers the key decisions you'll need to make when building forms in overlays, including how to format your forms and choosing the overlay size that best fits your content.
Sectioning
Use FormSections to group related fields in an overlay, depending on the type of overlay and the number of form elements present:
|
Type of overlay |
Dialogs |
Drawers |
|---|---|---|
|
Preview |
|
|
|
Method |
No sectioning |
Use static sectioning |
|
Number of elements |
Less or equal to 5 |
Less or equal to 10 |
|
Description |
Spacing is provided by the relevant FormSection component. |
Section contents are always visible. If there are more than 10 form elements or more than 2 sections are required, use a page with interactive sectioning instead. This is a recommendation. Interactive sectioning in Drawers may be required on a per-case basis, depending on the content and user flow. |
See Group fields into sections for related information.
Field sizing
In Dialogs and Drawers, use form fields at full-width. Exceptions are when form fields specifically cater for smaller inputs (like a Time or Date Picker) or do not display helper text. Avoid multi-column forms in overlays.
See Single and multi-column forms and Field sizing for further guidance.
Do use full-width form fields.
Do use certain form fields at a smaller width, like Time or Date Picker. These are intentionally smaller based on their expected inputs.
Be careful when building forms with many inconsistent input sizes. Consider the amount of expected input and the sizing of other fields.
Labels
Avoid duplicating the entity name in labels if it’s already mentioned in the overlay’s title (e.g., “Add new team” is the title, so labels can be simplified to “Name” and “Description” instead of “Team name” and “Team description”).
Do simplify labels where possible to make it easier for users to scan the form.
Don’t duplicate entity names in labels when already mentioned in the overlay’s title.
Dialog sizes
|
Dialog size |
small |
medium |
large |
|---|---|---|---|
|
Preview |
|
|
|
|
Description |
Compact size for simple content. |
Default size for a standard form. Works well for multiple form elements and makes longer copy legible. |
Larger size for complex form elements that require more real estate. |
|
Number of elements |
1-2 |
3-5 |
3-5 |
|
Type of content (examples) |
- Simple form elements with minimal or no helper text - Small amount of explanatory copy |
- Form elements with a sentence of helper text - Explanatory copy with more than a couple of lines of text - Form elements with longer labels or user inputs, like a description in a Text Field/Text Area, or files associated with the File Upload |
- Markdown Editor - Group of cards |
Drawer sizes
|
Dialog size |
small |
medium or wide |
|---|---|---|
|
Preview |
|
|
|
Description |
Default size for a standard Drawer. |
Larger size for complex form elements that require more real estate. |
|
Number of elements |
Less or equal to 10 |
Less or equal to 10 |
|
Type of content (examples) |
- Form elements with a sentence of helper text - Explanatory copy with more than a couple of lines of text - Form elements with longer labels or user inputs, like a description in a Text Field/Text Area, or files associated with the File Upload |
- Code Editor - Group of cards |
Test action
When using a Test Button in a Dialog or Drawer to let users preview an output from a form, add it to the main content area. It should not be included in the header or footer actions.
