Tag field usage guidelines

Tag field allows users to select multiple options from a filterable list of options.

When to use

• When users need to select more than one item from a long list of options.

When not to use

• Use checkboxes or radio buttons if there are 4 or fewer options in the list.
• Use checkboxes or radio buttons if there is a benefit to the user being able to see all options at once and compare what they have and have not selected.
• Use select or combo box when users should be able to select only one option from the list.
• Use text fields when the intended value is a user-entered string.

Usage

Preview

Favorite fruits

Code

import { TagField, TagFieldItem } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <TagField label="Favorite fruits" placeholder="Select fruits">
      <TagFieldItem>Apple</TagFieldItem>
      <TagFieldItem>Banana</TagFieldItem>
      <TagFieldItem>Cherry</TagFieldItem>
    </TagField>
  );
}

Tag field lists are composed of items and, optionally, list sections. For most use cases, a simple list of items without sections provides the clearest and most straightforward experience for users.

With sections

Preview

Favorite fruits

Code

import { TagField, TagFieldItem, TagFieldSection } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <TagField label="Favorite fruits" placeholder="Select fruits">
      <TagFieldSection title="Berries">
        <TagFieldItem>Strawberry</TagFieldItem>
        <TagFieldItem>Blueberry</TagFieldItem>
        <TagFieldItem>Raspberry</TagFieldItem>
      </TagFieldSection>
      <TagFieldSection title="Citrus">
        <TagFieldItem>Orange</TagFieldItem>
        <TagFieldItem>Lemon</TagFieldItem>
        <TagFieldItem>Lime</TagFieldItem>
      </TagFieldSection>
    </TagField>
  );
}

List sections can be used to categorize the items in a list if there’s a large number of options or if the added context helps users understand or differentiate list items. List section headings should be short, distinct, and clearly label the category of list items.

Formatting and layout

Placement

Tag field can either be left-aligned with the container it is placed in or, for smaller containers like modal dialogs and disclosures, it can span the full width of the container.

Spacing

• Tag fields should have at least 16px of horizontal and vertical spacing between the tag field and other elements.

Form alignment

Tag field can be used in forms in conjunction with the other form components (text field, checkbox, and radio button for example). Form element width should be determined by the width of the container, not the specific content in the individual element. When tag fields are stacked vertically with other elements (other tag fields, or other form components), all of the components should have consistent widths.

Do

Name

Favorite fruits

Don't

Name

Favorite fruits

Content writing

Label

• Do use a short description of just one or two words for the label such as “Attributes”.
• Do not format labels in the form of a question such as “Which attributes do you want to use?”
• Do not include verbs in your label such as “Select attributes”.

Placeholder text

• Placeholder text can be used to provide an example of user input but should not duplicate the label text.
• Placeholder text is optional and should only be used where more context is necessary for the user to understand.

List items

• List items should be ordered intentionally to make finding an option easier for users. They can be organized from most selected to least selected or alphabetically.
• Section headings should be short and clearly state how the section has been categorized.

Description text

• Do provide description text whenever the label might not be enough context for a user to understand the purpose of the tag field.
• Do not provide unnecessary description text when the options to be selected is obvious based on the label.
• Do write clear and concise description text. Text should be limited to one sentence.
• End the description text with a period or equivalent punctuation mark. This helps screen reader users understand where the description ends, and it improves readability for all users.

Error text

• Do provide clear and concise error messaging.
• Do explain the issue and let the user know what they need to do to resolve it. Error messages should always provide users with a solution or a path to resolving the error.
• Error messages should use language that is easily understood rather than complex technical terms.
• End the error message with a period or equivalent punctuation mark. This helps screen reader users understand where the error message ends, and it improves readability for all users.

Behaviors

Default selection

If a tag field has a common or suggested set of options that most users select, it can be populated by default with these options. The user should still be able to interact with the tag field component and choose different options.