Design Guidelines

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.

Form Layouts

Clarity offers three types of forms: horizontal (our recommended default), vertical and compact.

Horizontal - 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.

Vertical

This option is better for scanning, mobile experiences, accessibility, and localization. While it offers better completion rates, it is less ideal for longer forms.

Compact

For cases with highly limited space, we provide a compact form layout.

Form Architecture

Columns

Forms should help users complete their goal as quickly as possible. Column structure can help make it easier for users to complete your form.

Do

Put forms in one column. Multiple columns disrupt users’ vertical rhythm and completion.

Don't

Create multiple columns of input fields per page, except for small, related inputs like name “first” and “last.”

Input Grouping

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.

align inputs and labels
Do
don't have inputs misaligned
Do
don't right align inputs
Don't

Form Length

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.

Form Elements

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.

Validation and Error Messaging

You also want to let users know when something is wrong with the information provided.

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.

Do

Place icons outside the input field. This will also help avoid browser and third-party app collision conflicts.

Don't

Put icons inside the input field. If inside, account for changing form value space (increase characters).

Error Message Content

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.

Error Message Location

We recommend displaying error messages within the same area where the error occurs.

Error Message Behavior

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.

The UX design guidelines documentation is currently a work in progress, and will be updated when they are ready.

Forms Accessibility

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.

Without the 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.

Deprecation: Since v4, we will no longer handle setting aria-live and announcing the message for you by default. Based on the application use case, you can use the new ClrAriaLiveService to make announcements when they make sense for a user to hear about updates or loading status changes.

Forms Using Angular

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.

Basic form

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.

Layout options

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.

Basic structure

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.

Helper and validation messages

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 screenreaders) to read, with research to back this up compared with the use of a red required asterisk (*). See this article from fusionbox provides some evidence for this rationale.

Multiple error messages

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. Optionally, you can access the error object *clrIfError="'errorName'; error as err" to customize the error message.

Reset and force validation

All Clarity form controls support resetting the validation state simply by calling the reset() method on the FormControl or FormGroup.

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.

Layout with grid

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.

Overriding column widths

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.

Reactive Forms

Forms also work with reactive forms with the same support for validations.

Custom and non-Clarity Controls

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!

Forms with CSS

If you want to use just the HTML/CSS for building your own form controls, this section describes how to use them. If you are interested in how to use it with Angular, please jump to the Angular section.

Basic form

A Clarity form first must include the .clr-form class, typically on the form element itself.

Layout options

Forms support three layout options, horizontal, vertical (used if no classes are provided), and compact. You can change the layout by simply applying an additional class to the form.

Basic structure

Each control that you add inside has a similar structure, and they are each covered in their own documentation. However, the general structure is like this for a normal text input.

Layouts with grid

If you choose to use a layout other than vertical, you should also provide the corresponding grid classes to allow the form layout to dynamically switch to vertical for narrow width devices. Excluding this may cause experience issues with mobile or narrow widths.

Error state

For error states, you simply need to add the clr-error class to the clr-control-container element. This will automatically display the error icon, turn the input outline to red, and change the color of the subtext to red. It is recommend that you change the content of the subtext for error messages, but that is up to the application to manage.

View documentation for each form control to get specifics on their HTML structure.