- Taxonomic name: M-FORM-ROW
- Added on: v3.0.0 (15/09/17)
- Updated on: v5.5.0 (23/03/21)
Form row
Form rows are built to work with the full width of the page and restrict form fields to six columns for medium and large screen sizes.
Design and usage
- Field labels should be displayed outside of the input field.
- Ensure fields have a correctly associated label; this not only provides context to each field for assistive technology users, but also provides a larger clickable area to select the field.
- Clicking / pressing on a label for a field should cause the input to gain focus.
- Users should be allowed to copy and paste if necessary.
- See style guide for detailed colour and typography rules.
Mandatory field indication
- All form fields within a form that are mandatory are not marked. Optional form fields must be indicated as part of the form label by placing "(optional)" at the end of the text.
Accessibility
- A visually hidden instruction that informs the user that all fields are mandatory unless otherwise stated must preceded any form containing required fields.
- All required fields must also include the
aria-required
attribute to ensure that the required fields are correctly announced to the user. The required attribute should be used with caution as it can cause fields to be highlighted as an error before a user are interacted with them. - Aria-invalid must be used to indicate when an error has occurred with this element.
- Aria-describedby must be used to link any help, instructional and/or error text with the element/form fields.
Examples
Standard form row
Interactive example
Code example
<div class="m-form-row [ Modifier ]">
<label class="a-label" for="...">...</label>
<div class="m-form-row__content">
...
</div>
</div><!-- or --><fieldset class="m-form-row">
<legend class="a-label">...</legend>
<div class="m-form-row__content">
...
</div>
</fieldset>
Valid form row
Interactive example
Code example
<div class="m-form-row [ Modifier ] is-valid">
<label class="a-label" for="...">...</label>
<div class="m-form-row__content">
<p class="m-form-row__validation-message">...</p>
...
</div>
</div>
Errored form row
Interactive example
Code example
<div class="m-form-row [ Modifier ] is-error">
<label class="a-label" for="...">...</label>
<div class="m-form-row__content">
<p class="m-form-row__error-message" id="..."><span class="u-hidden--visually">Error: </span>...</p>
...
</div>
</div>
Disabled form row
Interactive example
Code example
<div class="m-form-row [ Modifier ] is-disabled">
<label class="a-label" for="...">...</label>
<div class="m-form-row__content">
...
</div>
</div>
Development and test
Notes for developers
Form rows are built to work within the full width of the page and restrict the
form fields to a 6 columns at medium and large screen sizes. If the form is
required to sit within a narrower area the modifier class m-form-row--full-width
can be added, but the
container must not be wider than 6 columns at medium and large screens.
Field labels should be displayed outside of the input not inside.
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.
If the native form validation needs to be disabled set the novalidate
attribute on the form.
Required fields
Ensure that a visually hidden message precedes any form that contains required fields. For example:
<p class="u-hidden--visually">All fields are mandatory unless otherwise stated</p>
Ensure that all required fields have aria-required
attribute set on them or their group. For example:
<-- Basic input -->
<input type="..." id="..." name="..." value="..." aria-required="true" /><!-- checkbox, radio or input group -->
<fieldset class="m-form-row" aria-required="true">
<legend class="a-label">...</legend>
<div class="m-form-row__content">
...
</div>
</fieldset>
Do not use the HTML5 required
attribute in
conjunction with the aria-required
attribute as it
will cause screen readers to repeat that the field is required. The HTML5
required attribute is also not implemented uniformly across browsers and tends
to invoke undesirable behaviour (marking empty fields are invalid from the
outset).
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.
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 |
Base wrapper for a form row | Yes | div, fieldset |
|
.a-label |
Label styling | Yes | .m-form-row > label, fieldset.m-form-row >
span |
The legend for a fieldset of radioes or radio buttons sits within the 'a-label' span |
.m-form-row__content |
Styling for content within the form row | Yes | .m-form-row > div |
|
.is-disabled |
Styling for a disabled text area | .m-form-row |
||
.is-error |
Styling for an errored text area | .m-form-row |
||
.m-form-row__error-message
|
Styling for an error message |
m-form-row__content > p
m-form-row__content > div
m-form-row__content > span
|
Must be displayed after any help text. If using a |
|
.is-valid |
Styling for an validated text area | .m-form-row |
||
.m-form-row__validation-message |
Styling for an validation message |
m-form-row__content > p m-form-row__content > div m-form-row__content > span
|
Must be displayed after any help text. If using a |
|
m-form-row--full-width |
Modifier to make the form row go full width within its container | .m-form-row |
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.