Form Pill Group

A Form Pill Group is an editable set of Pills that represents a collection of selectable and/or removable objects. They are used almost exclusively in multi-select editing situations.

A Form Pill Group can be used on its own to represent selection across a number of fields, such as showing currently applied filters. It can also be paired directly with an input field, such as a Combobox, to represent multiple selections.

The only accessibility requirement is providing the Pill Group a descriptive label via the aria-label React prop.

The Form Pill Group is focusable, but only one pill is focusable at a time. This means the Pill Group is a single tab stop to a keyboard user. The dismiss button in a Form Pill is not a focusable element, but can be clickable.

Once a user focuses within the Form Pill Group, they can use these keyboard interactions:

Form Pill Group creates a list from which a user may select items, whereas a Display Pill Group creates a list of static items.

Use the table below to get a better understanding of when to use Form Pill or Display Pill.

This Form Pill example shows the basic static component that's exported by Paste. A Form Pill can have an optional Avatar or Icon placed before the text.

Interaction states on Form Pills need to be managed separately as shown in the examples after this one by using the useFormPillState hook. The returned state should be spread onto each component. This will provide you with some internal state management and keyboard navigation.

A Form Pill can have an optional Avatar or Icon placed before the text.

Use size="large" Form Pills only for specific and approved use cases, such as in the filter pattern.

Use a Selectable Form Pill to show an option that a user can select or deselect.

To make pills inside the Pill Group selectable, you can manage the selection state yourself and combine it with the state returned from the useFormPillState hook. To do so, track which pill is selected in a separate store of state. When rendering the Form Pill Group, cross reference the rendered pills with the selection state, and conditionally set selected on each FormPill that requires it.

The onSelect event handler will fire whenever the pill is clicked, or the spacebar or enter key is pressed. Use this to respond to your users' selection interactions.

Use a Dismissible Form Pill to show an option that a user can remove from the group. Once the pill is dismissed, it can’t be rerendered.

Form Pills are given a close button when provided an onDismiss event handler. Because the Form Pill Group is largely presentational, provide dismissible functionality by managing the state of the rendered pills. By responding to user interactions and hooking into the onDismiss event handler, the rendered state of the Form Pill Group can be updated and pills can be selectively removed from the collection.

The onDismiss event handler will fire when a user clicks on the close button, or presses their backspace or delete key when focused on a pill.

Use a Selectable and Dismissible Form Pill to show an option that a user can select, deselect, or dismiss. Once the pill is dismissed, it can’t be re-rendered.

The onSelect event handler will fire when a user clicks on the pill. The onDismiss event handler will fire when a user clicks on the close button.

The onSelect event handler will fire when a user presses the spacebar or enter keys. The onDismiss event handler will fire when a user presses the delete or backspace keys.

The tree variant for FormPillGroup changes the accessibility roles and DOM elements of the FormPill to be more tree-like where selecting the pill expands more options. This variant of Form Pills is only for specific and approved use cases, such as in the filter pattern.

To internationalize the form pill group, simply pass different text as children to the pills. The only exceptions to this are the visually hidden text that explains how to dismiss and select pills and the error label for the error variant. To change these, pass the i18nKeyboardControls and i18nErrorLabel props.

The default state of a Form Pill indicates that the control is static or not selected.

A Form Pill can be placed into a selected state by setting the selected property.

Use an Error Form Pill to highlight an object that the user must be made aware of because it’s considered to be in a bad or broken state and should be addressed. An error icon will display as a prefix to the rest of the children in the pill.

When used in a form field, display an error message below the form field to provide guidance on how to fix the error. For additional guidance on how to compose error messages, refer to the error state pattern.

Use a disabled Form Pill to indicate that a particular option cannot be interacted with or can be safely ignored.

Pill text should never wrap to the next line. If the text length is longer than the max width of the pill group’s container, consider moving the Pill to a new row or use Truncate to truncate the Form Pill text.

A Form Pill can have an optional Avatar. Considering the size of a Form Pill, it is recommended to use either an image or icon within an Avatar, and to avoid using initials as some initials may get cut off if the characters are particularly wide.

We recommend placing the Avatar ahead of the pill text. Use no more than one before or after the text.

A Form Pill can have an optional Icon. We recommend placing the Icon ahead of the pill text. Use no more than one before or after the text.

Use a Form Pill Group when you’re editing a collection of data within a form. It can be used to represent selection across multiple fields such as filtering, or from a single field like a Combobox.