Forms are a grouping of input controls that allow a user to submit information to your application.
Forms are comprised of text and input components such as checkboxes, dropdowns, input fields, radio buttons, and toggle switches. The easier users can complete forms, the better your response rates will typically be. Forms should be clear, concise, and relevant to its context.
Clarity offers three types of forms: horizontal (our recommended default), vertical and compact.
Default Horizontal formats are good for the quick scanning of labels, and can be used in cases of limited vertical space. The space between label and input however can slow users down.
This option is better for scanning, mobile experiences, accessibility, and localization. While it offers better completion rates, it is less ideal for longer forms.
For cases with highly limited space, we provide a compact form layout.
Forms should only be as long as absolutely necessary. We recommend reviewing each form input and asking whether you could obtain the information in another way, or at a later, more convenient time.
Forms should help users complete their goal as quickly as possible. Column structure can help make it easier for users to complete your form.
Grouping will make scanning easier. A form with more than 6 inputs will likely have inputs that can be grouped together, like “address”: street, city, zip, county, country, etc.
For the grouping of labels and their input fields, we recommend grouping labels closely with their respective input fields.
Radios, Checkboxes, and Select Box For inputs with 3 or more options, you may use radios, checkboxes or select boxes. We recommend placing your options vertically in one column to make it easier to scan.
Radios and checkboxes are used when it is helpful to compare options within the context of the form, as all selections will be visible at all times. Select boxes typically have more than 7 options that do not need to be compared with each other.
Error Message Styling When showing error inputs, highlight the input field with red in some way, but also pair the red with another visual indicator, like an icon. This will help with accessibility.
You also want to let users know when something is wrong with the information provided.
For most cases, validate when the user leaves the field (onblur). Invalidating fields while users are still typing can be frustrating.
There are some cases where real-time validation can be helpful, such as inputs with sensitive field value lengths (like tweets), or when users return to an error field and successfully edit the error field, or for password fields with visible password strength criteria.
We recommend displaying error messages within the same area where the error occurs.
Humanize the error messaging as much as possible. The content should provide clear guidance on how to fix the error. Avoid unrecognizable system error messages like "code 500 error". You may also consider using more than one error message when helpful. For example, if an email address input field has an error, consider either showing “please enter an email address” for a blank field, or “email address needs an ’@’ symbol followed by a domain” for an invalid symbol.
Clarity form controls are built with
clr-CONTROLNAME-container elements. These elements are used to build in the accessibility needed to make Clarity forms accessible. While it is control dependent, the containers enable screen readers to be aware of errors both on the control itself and in the form as a whole. They enable the behaviors that describe controls with their respective labels that in an accessible way.
clr-CONTROL-container parent the forms and form controls are not accessible. In the examples below and on the documentation page for each control you can find example markup for making the forms and form controls accessible.
Finally, for screen readers, if there are any controls with errors after the submit action an
aria-live region will be updated with the associated labels for each control in the error state.
Clarity has created a set of directives to help manage forms with minimal effort by developers. The structure is more condensed and easier to implement, so it is the recommended approach to use the following if you are using Angular. More form controls are being added regularly.
Then declare a form start by adding the
clrForm directive to the form element. This will wire up some internals to manage the form itself.
If you wish to have a different layout, then you can use the
clrLayout directive to set the desired layout. The appropriate grid classes will be applied to enable automatic layout switching for mobile viewports.
When you start to fill in your form controls, each will should be wrapped in a container like you see here in this text input example.
These Angular components also support built in helper text and validation with error messages.
All fields should be assumed to be required. Clarity does not support a required input treatment for labels (which often comes in the form of an * by the label). The recommendation is to focus your forms to include only required fields, and if a field is optional then you can describe it as such in the label like (Optional).
For screen reader accessibility, forms with validation messages should provide a descriptive message on how validation messages will be triggered. The
.clr-sr-only class will hide content and only make it visible for screen readers.
This pattern is more accessible and clear by writing the word "error" explicitly for users (and screen readers) to read, with research to back this up compared with the use of a red required asterisk (*). See this article from fusionbox (opens new window) provides some evidence for this rationale.
If you want to support multiple error messages, you can do this by defining an error message for each scenario using
clrIfError. It is recommended that you create an error message for each validator you specify. Use the validator name provided in the binding for
*clrIfError="'errorName'", which might be your custom validator or a built in Angular one.
All Clarity form controls support resetting the validation state simply by calling the
reset() method on the
Normally, validation errors only appear after the control has been focused on by the user. In cases where you want to force validation errors to show (such as when the user tried to submit a form), you simply need to mark every control as touched with Angular. You can use the form API to accomplish this,
ClrForm.markAsTouched(), which will force all form controls inside of a form to be touched, which will display the validation errors.
You can use the
clrLabelSize directive to configure the label width for an entire form. This is useful for
horizontal and compact layouts, but doesn't apply when you are using
vertical layout. It will accept a number between 1-12 to calculate the width according to our grid, and the controls will adopt the remaining size. For example if you pass
clrLabelSize="4" it will size the controls to use 8 grid columns for a total of 12 columns.
For horizontal layouts, you can override the default widths for labels (2 columns) and controls (10 columns). Even on horizontal layouts, the default behavior should still use a vertical layout for narrow mobile sizes. That means you should always include the class
clr-col-12 on both the input and label. Ensure your override columns add up to 12 to use the full space.
Forms also work with reactive forms with the same support for validations.
Applications often have form controls that are not supported by Clarity directly. To make these controls work nicely with Clarity, you can wrap them in a generic control container. Regardless if you make your own form controls or import a third party control, the generic container should help make your controls more consistent. The only requirement is that the form control works with Angular forms (Reactive or Template-Driven).
The basic process is to wrap the form control in the
clr-control-container component, and then apply the
clrControl directive to the form control itself.
It is likely that you'll have to write some CSS rules to make the custom controls fit and look correct within the generic control container. Use specific selectors to avoid changing the default form control behaviors in other parts of the application!