TagField

The <TagField> component allows users to select multiple options from a dropdown list. Selected items are displayed as removable tags directly inside the input area, giving users a clear overview of their choices at a glance. The component includes a built-in search field for quickly filtering through large option sets.

<TagField> is ideal for scenarios where users need to pick several items from a predefined set, such as assigning categories, tagging content, or selecting multiple preferences. Unlike a standard multi-select dropdown, the tag-based display provides immediate visual feedback and makes it easy to add or remove individual selections.

The component is built on react-aria, providing full keyboard navigation, screen reader support, and accessible interactions out of the box.

Anatomy

A <TagField> consists of a label, a trigger area with tags and an add button, and a popover containing a search input and an options list.

• Label: Descriptive text guiding the user on what to select.

• Container: The container area that displays selected tags and the button.

• Tag: A removable chip representing a selected item. Users can click the remove icon to deselect.

• Button: An icon button that opens the dropdown popover to add more selections.

• Search input: A text field inside the popover that filters the available options as the user types.

• Popover: The overlay container holding the search input and options list.

• Section: A group of related options with a header label, used to organize options into categories.

• Option: An individual selectable item in the dropdown list.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Usage

The <TagField> works best when users need to select multiple items from a list of options (10+) and want to see their selections displayed compactly as tags. It combines filtering (typing to narrow down options) with visible selection feedback, saving space compared to checkboxes.

Organizing options into sections

When the list of options becomes large or covers distinct categories, grouping them into sections helps users find what they are looking for. Use the <TagField.Section> component to wrap related options, providing a header for each group to add structure and context.

import { useState } from 'react';import { Key } from '@react-types/shared';import { TagField } from '@marigold/components';const categories = [  {    name: 'Rock and Alternative',    genres: [      { id: 'rock', name: 'Rock' },      { id: 'indie', name: 'Indie Rock' },      { id: 'punk', name: 'Punk Rock' },      { id: 'grunge', name: 'Grunge' },    ],  },  {    name: 'Electronic',    genres: [      { id: 'house', name: 'House' },      { id: 'techno', name: 'Techno' },      { id: 'ambient', name: 'Ambient' },    ],  },  {    name: 'Jazz and Blues',    genres: [      { id: 'jazz', name: 'Jazz' },      { id: 'blues', name: 'Blues' },      { id: 'bebop', name: 'Bebop' },    ],  },];export default () => {  const [selected, setSelected] = useState<Key[]>([]);  return (    <TagField label="Genres" value={selected} onChange={setSelected} width={80}>      {categories.map(category => (        <TagField.Section key={category.name} header={category.name}>          {category.genres.map(genre => (            <TagField.Option key={genre.id} id={genre.id}>              {genre.name}            </TagField.Option>          ))}        </TagField.Section>      ))}    </TagField>  );};

Preventing selection of specific options

In some cases, certain options should be visible but not selectable. For example, an option may be temporarily unavailable or restricted based on the user's permissions. Use the disabledKeys prop to mark specific options as non-interactive while keeping them visible in the list.

import { useState } from 'react';import { Key } from '@react-types/shared';import { TagField } from '@marigold/components';export default () => {  const [selected, setSelected] = useState<Key[]>([]);  return (    <TagField      label="Genres"      value={selected}      onChange={setSelected}      disabledKeys={['classical', 'electronic']}      width={80}    >      <TagField.Option id="rock">Rock</TagField.Option>      <TagField.Option id="jazz">Jazz</TagField.Option>      <TagField.Option id="pop">Pop</TagField.Option>      <TagField.Option id="classical">Classical</TagField.Option>      <TagField.Option id="electronic">Electronic</TagField.Option>    </TagField>  );};

Keep option text concise

Option labels should be short and scannable so users can quickly identify the items they need. Long or overly detailed labels slow down the selection process, especially when users are filtering by typing in the search field.

Labeling

For general guidance on labels, placeholders, and help text, refer to the Form Fields foundation page.

Accessibility

The <TagField> supports full keyboard navigation through all its interactive parts.

When the popover opens, the search input receives focus automatically, allowing users to immediately start filtering options by typing.

Props

TagField

TagField.Option

TagField.Section

Alternative components

• ComboBox: When users need to select a single value from a filterable list, or when they should be able to type a custom value.
• Select: When users need to choose a single option from a dropdown without a search field.
• SelectList: When you need more than just a text label to represent options and want a persistent, visible list.
• Checkbox: When there are fewer than 10 options and all choices should be visible at once without a dropdown.

Related