Form styleguide
Pulsar form helpers provide all the necessary markup and styling required to build a responsive, robust form layout. All helpers provide a set of common options allowing you to provide useful labels, placeholders and guidance popovers or indicate whether fields are required or in an error state.
Accessibility
Pulsar form helpers are designed to make building accessible forms as easy as possible, however there are a few things you will need to consider and test for.
How to test
Use the WebAim Web Accessibility Evaluation Tool's Chrome extension (WAVE) to view your UIs and resolve any 'red flag' errors as part of your normal testing process. You should spend some time familiarising yourself with the WAVE tool and the types of errors it will highlight. Remember, the absence of errors does not necessarily indicate that a given UI is accessible, but it will help catch accessibility errors that break WCAG 2.0 AA compliance.
Use IDs in form helpers
If you're using form helpers, you must supply an id
attribute. Pulsar's form helpers will automatically link both the label and the input so that screenreaders will correctly announce the elements.
Labelling standalone inputs
There may be times when a design calls for an input without an explicit label next to it, but can still be labelled by another element, such as a table heading column label.
To do this, the element acting as the label must have an id
, we recommend namespacing IDs used only for labels as id="aria-something"
so that other developers will understand that this ID exists for accessibility reasons. No styles or javascript behaviour should be hooked into aria-
namespaced IDs.
Example
<table>
<thead>
<tr>
<th id="aria-foo">Select</th>
</tr>
</thead>
<tbody>
<tr>
<td>
{{
form.checkbox({
'id': 'foo',
'aria-labelledby': 'aria-foo'
})
}}
</td>
</tr>
</tbody>
</table>
Validation states
All form helpers can be styled with the validation state classes through the class
option. The helpers will style their labels and help text appropriately. For error states, you should use the error
option of the form helper to also pass an error message to the field.
Error
Highlight fields that contain invalid values which will need resolving before a form can be successully submitted. This class is automatically set when using a form helper's error
option.
.has-error
See the Pen docs - form - text error states by Pulsar (@pulsar) on CodePen.
Success
Show that a field has the expected value, or that it has been saved/updated successfully.
.has-success
See the Pen docs - form - text success by Pulsar (@pulsar) on CodePen.
Warning
Use to highlight non-critical issues with form data, such as a textarea containing too many characters than we'd recommend.
.has-warning
See the Pen docs - form - text warning by Pulsar (@pulsar) on CodePen.
Changed
Use to visually highlight when a field value may have changed. Particularly important if a user updating one field causes another field to change.
.has-changed
See the Pen docs - form - text changed by Pulsar (@pulsar) on CodePen.
Placeholders
A hint to the user of what can be entered in the control.
Do not use the placeholder attribute instead of a <label>
element. Their purposes are different: the <label>
attribute describes the role of the form element; that is, it indicates what kind of information is expected, the placeholder attribute is a hint about the format the content should take. There are cases in which the placeholder attribute is never displayed to the user, so the form must be understandable without it.
Placeholders should:
- Not have a full stop at the end
{{
form.text({
'label': 'National Insurance Nō',
'id': 'text-example-1',
'placeholder': 'AB 12 34 56 C'
})
}}
See the Pen docs - form - text placeholder by Pulsar (@pulsar) on CodePen.
Help text
It's almost always preferable to use help
instead of placeholders, as these aren't hidden as soon as the input has focus.
Help text should:
- Use sentence case
- Not have a full stop at the end
{{
form.text({
'label': 'National Insurance Nō',
'id': 'text-example-2',
'help': 'You can find this on your payslip. For example, AB 12 34 56 C'
})
}}
See the Pen docs - form - text help by Pulsar (@pulsar) on CodePen.
Guidance
Provide extra information to help a user understand a form field. Guidance is only shown when the user clicks or taps on the question mark symbol so should not be used to contain critical information where help
would be more appropriate.
{{
form.text({
'label': 'Keywords',
'id': 'foo',
'guidance': 'Keywords aren’t used by most search engines and using too many can harm your site’s position in their rankings'
})
}}
See the Pen docs - form - text guidance by Pulsar (@pulsar) on CodePen.
Input widths
Modify your input widths to suit your expected inputs, if you only want two digits there’s no point using a full width field.
The following width classes are available:
form__group--mini
form__group--small
form__group--medium
form__group--regular
form__group--large
form__group--xlarge
form__group--full
Passing a width via the form helper's class
attribute will apply it to the form group. For example, applying form__group--full
:
<div class="form__group form__group--full">
<label class="control__label">Label</label>
<div class="controls">
<input id="foo" name="foo" type="text" class="form__control">
</div>
</div>
If you require more fine-grained control you can apply the same width classes to specific form controls.
form__control--mini
form__control--small
form__control--medium
form__control--regular
form__control--large
form__control--xlarge
form__control--full
<div class="form__group">
<label class="control__label">Label</label>
<div class="controls">
<input id="foo" name="foo" type="text" class="form__control form__control--full">
</div>
</div>
Width Examples
{ 'class': 'form__group--mini' }
See the Pen docs - form - text mini by Pulsar (@pulsar) on CodePen.
{ 'class': 'form__group--small' }
See the Pen docs - form - text small by Pulsar (@pulsar) on CodePen.
{ 'class': 'form__group--medium' }
See the Pen docs - form - text medium by Pulsar (@pulsar) on CodePen.
{ 'class': 'form__group--regular' }
See the Pen docs - form - text regular by Pulsar (@pulsar) on CodePen.
{ 'class': 'form__group--large' }
See the Pen docs - form - text large by Pulsar (@pulsar) on CodePen.
{ 'class': 'form__group--full' }
See the Pen docs - form - text full by Pulsar (@pulsar) on CodePen.
Label alignment
The default style of forms is to have the label next to the input however there are a couple of alternatives which might work better, depending on your form’s needs.
Top label
{ 'class': 'form__group--top' }
See the Pen docs - form - top label by Pulsar (@pulsar) on CodePen.
Flush top label
{ 'class': 'form__group--top form__group--flush' }
See the Pen docs - form - top label flush by Pulsar (@pulsar) on CodePen.
Indented elements
Often you will need to use elements other than full form inputs which you to be aligned with the other form inputs. Use the indent class to arrange these, either on a single element or on a wrapper element.
{ 'class': 'form__indent' }
See the Pen docs - form - indented button by Pulsar (@pulsar) on CodePen.
Regular HTML elements
See the Pen docs - form - regular elements by Pulsar (@pulsar) on CodePen.
Appended and Prepend inputs
Inputs can be prepended and appended with icons, text or buttons to provide additional visual hints or context to a field.
The following options are available to almost all form helpers.
Option | Type | Description |
---|---|---|
append | string | Text or markup to include after the input element |
append_type | string | Use only when appending a button. button is the only valid value |
prepend | string | Text or markup to include before the input element |
prepend_type | string | Use only when prepending a button. button is the only valid value |
{{
form.text({
'label': 'Amount',
'prepend': '£'
})
}}
See the Pen Appended and prepended icons and text by Pulsar (@pulsar) on CodePen.
Whilst buttons can be used to link an input to a related action:
{{
form.text({
'label': 'Postcode',
'placeholder': 'For example, LE19 1RJ',
'append': html.button({ 'label': 'Find' })
})
}}
See the Pen Appended and prepended buttons - postcode example by Pulsar (@pulsar) on CodePen.
Like icons and text, buttons can be appended, prepended or both:
See the Pen Appended and prepended buttons by Pulsar (@pulsar) on CodePen.