- Taxonomic name: M-FORM-ROW__EXPLANATORY-TEXT
- Added on: v3.0.0 (15/09/17)
- Updated on: v5.5.0 (23/03/21)
Explanatory text
Explanatory text surfaces important concise information or 'hints' for visibility to users completing form inputs. Be selective in their application and consider whether they are really needed - forms shouldn't require extensive completion instructions.
Design and usage
- Use where there are specific 'hints' that will inform data input (although a user's preferred data entry format should be accommodated where possible).
- Use where users may not be familiar with the data being asked for (such as policy number).
- Use where more information may be required on why something is being asked.
- Use where information needs to be provided about security or use of data.
- Information should be concisely written to support scanning - longer pieces of information should be catered for within help text.
- A text link may be used for in instances such as forgotten password details.
- See the style guide for detailed typography guidelines.
Explanatory text links
Structure
- Can only be used in form journeys for example login page.
- Can only be used with basic form elements such as single textbox, dropdown.
- Can not be used with radios, checkboxes, form row groups etc.
- Do not use with contextual help within the same form row.
- Link placed to the right should only be used to help the user in recovering from their journey.
- For text that helps the user or has explanatory text consider using explanatory text, contextual help or show more pattern.
Placement
- Links are placed to the right of a form field label.
- Link should be placed underneath and to the right of a form field label and above the form field when a label is too long and causes the link to wrap.
Accessibility
- Links must be tertiary buttons to ensure there is a large enough hit target.
- Aria-describedby must be used to link the explanatory text with the appropriate fieldset/form field
Examples
Standard explanatory text
Interactive example
Code example
<div class="m-form-row">
<label class="a-label" for="...">...</label>
<p class="m-form-row__explanatory-text" id="...">...</p>
<div class="m-form-row__content">
...
</div>
</div>Explanatory text link
Interactive example
Code example
<div class="m-form-row m-form-row--has-explanatory-text-link">
<label class="a-label" for="...">...</label>
<p class="m-form-row__explanatory-text-link" id="..."><a href="..." class="a-button a-button--tertiary [ Modifiers ]"><span class="a-button__inner">...</span></a></p>
<div class="m-form-row__content">
...
</div>
</div>Development and test
Notes for developers
If an explanatory text link is to be used in conjunction with standard explanatory text the text link must be first.
Can only be used in form journeys: for example login pages.
Can only be used with basic form elements, such as single textbox, dropdown.
Can not be used with radios, checkboxes, groups of textboxes etc.
Do not use with contextual help within the same form row.
Link placed to the right should only be used to help the user in recovering from their journey.
For text that helps the user or has explanatory text consider using explanatory text, contextual help or show more pattern.
The explanatory text link must only ever be used in conjunctions with basic form elements ie. single textbox, dropdown; do not use with form elements such as radios, checkboxes etc. If an explanatory text link is to be used in conjunction with standard explanatory text the text link must be first.
When including an explanatory text link ensure that a tertiary button is used rather than a standard link. This ensure that the hit target is large enough to comply with WCAG guidelines.
When disabling form elements, do not solely rely on the is-disabled class, but ensure that the disabled attribute is also set on the relevant form element or input. If an entire set of form elements is to be disabled, the is-disabled class and disabled attribute should be added directly to the fieldset instead, and not to each individual element within it. However if only one element from the set is disabled, then the class and attribute should be applied to that element only.
Aria usage for errors and help text
To aid screen reader users in completing forms without error and also with understanding and fixing any errors that have occured, some additional aria attributes are now recommended to be applied across all form fields/rows.
All form row help, explanatory text, form row instructions and form row errors must have a unique id assigned to them and be appropriately linked to either the individual form input or the form row using aria-describedby. This ensures that the help text is read out immediately on focus of the form input/fieldset. When there is more that one item that requires referencing within the aria-describedby attribute the id values must be supplied in the form of a space separated list. For example if there is an error with id of 'err1' and help text with id of 'help1' the value for the aria-describedby attribute would be 'err1 help1'.
All inline form error messages should start with the hidden text 'Error: ' so that when read by out by a screen reader it is immediately clear that the text being read is an error message.
All erroring form fields (or fieldset if a group or radios/checkboxes) must have aria-invalid="true" set on them, ensuring that when a user focus' on an errored form field, the field will be announced as invalid, so the user is then aware that there in an issue that requires fixing.
When linking help or errors, or even adding aria-invalid to the markup careful consideration must be taken as to where it is most appropriate to apply the value. The following rules should be used to decide where the attribute(s) should be applied.
- Single form field - All attributes should be applied directly to that form field
- Group of form fields but only one in error or help text applies to only one - Apply the attribute(s) to the only field in error or where the help text applies
- Group of form field where all in error or the help text applies to all - Apply the attribute(s) to the groups surrounding fieldset (form row)
There may situations where more than one of these rules applies to the overall form row for example a date range where the instruction text applies to both fields so should be linked to the fieldset for the date range but one of the two fields is in error so the error should be linked to just that field not to the fieldset.
Notes for testers
- Ensure that any links can be accessed via the mouse as well as via tabbing using the keyboard.
- Ensure that when hovering over any links the style changes noticeably.
- Ensure that when a link has focus the style changes noticeably.
Classes overview
The following table gives you a quick overview of the CSS classes that can be applied.
| Class | Outcome | Required | Applied to | Comments |
|---|---|---|---|---|
.m-form-row__explanatory-text |
Base styling for some explanatory text | Yes | .m-form-row > .a-label + p |
|
.m-form-row--has-explanatory-text-link |
Modifier for a form row that contains an explanatory text link | Yes | .m-form-row |
Only required for an explanatory text link |
.m-form-row__explanatory-text-link |
Base styling for an explanatory text link placed to the right of the form label | Yes | .m-form-row--has-explanatory-text-link > .a-label + p |
Must be used in conjunction with .m-form-row__explanatory-text-link |
Keyboard operations
- TAB
-
Tabbing to a link the link should become clearly visually different so that the focus point on the page is obvious to the user.
- SPACE or ENTER
-
With focus a link, pressing SPACE or ENTER will open the link.
Component releases
- Added on: v3.0.0 (15/09/17)
- Updated on: v5.5.0 (23/03/21)
Latest update:
- updated: Additional aria attributes are now recommended to be applied across all form fields/rows so as to aid screen reader users in completing forms without error and also with understanding and fixing any errors that have occurred.