Patterns

Forms

We use forms to collect information from users and to allow users to configure options. There are two types of inputs used in forms: text inputs and data inputs.

Text Inputs

Text inputs are used whenever users are required to manually enter text inside an input field. Text inputs must display top-aligned labels in all instances, and a character count in instances where a maximum number of characters is allowed.

Optionally, text inputs may display a toggletip next to the input label that contains supplementary information, placeholder text inside the input field to guide users in filling it out, and/or help text below the input field for further guidance or details.

For text inputs requiring multiple lines of text, use an expanding text area instead of a singular field.

Examples of text inputs’ and text areas’ anatomy and structure in non-active and active states.

Data Inputs

Data inputs refer to form elements that allow users to select inputs from a pre-determined set of options or a limited range of values. Below are examples of available form elements and a guide for appropriate usage of each element.

Form Element Usage
Checkbox
To select one or more options from a list
Radio Button
To select one option from a list
Multiselect
To select multiple items from a longer list. Use a multiselect instead of checkboxes for lists containing more than five items
Toggle To select one of two binary options (such as on/off, yes/no, etc.)
Datepicker To select a single date or a range of dates from a calendar
Timepicker To select or input a specific time or a range of time
Uploader To upload and attach one or more files to a form
Tag Input To create a tag or search through a pre-populated list of tags to add a tag

Do’s and Don’ts for Forms

Do:

  • Keep form input labels concise and in title case.
  • Use help text to give additional, specific details or guidance.
  • Use toggletips sparingly and only for supplementary information.
  • Reflect the width of the form field to the expected length of the content inside it wherever possible.
  • Use expanding text areas instead of single field text inputs whenever multiple lines of text is expected.
  • Group inputs for related tasks under section titles for longer forms.
  • Mark required fields with an asterisk. View guidelines for Required Fields for more details.

Don't:

  • Omit labels for any inputs.
  • Use placeholder or help text in place of input labels.
  • Provide placeholder or help text unless necessary.
  • Keep essential information hidden inside toggletips.
  • Use radio buttons and checkboxes for lists longer than five items. Instead, use a dropdown or multiselect.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.