Multi Select Field

For development, import MultiSelectField from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Multi Select Field consists of eight elements that work together to allow users to search and select multiple values from a list of options.

Placeholder text
Popover
Option
Selected value
Clear button (Optional)
Section header
Selected optio
Rich content option

Options

The Multi Select Field supports the following configurations to accommodate a wide range of selection scenarios.

Selection options

Search

By default, Multi Select Field provides a searchable text input that filters options as users type.

Select-only

When search adds no value — such as with short, well-known option lists — disable it to present a simpler select-only trigger. The select-only mode uses the listbox ARIA pattern instead of combobox. Multi Select Field displays options in a popover by default on desktop and a dialog on mobile. Override this adaptive behavior by setting the display mode explicitly to always use a popover or always use a dialog.

In a Dialog

Sections

Sections divide options into labeled groups, helping users scan and identify related items. Every section requires a label.

Pinned sections

Sections can be pinned to the top of the list. Pinned sections are useful for surfacing frequently used options, recent selections, or AI-powered suggestions without requiring the user to search for them.

Rich content

Options support rich content including titles, descriptions, avatars, icons, and chips. Rich content helps users distinguish between similarly named items or convey additional metadata at a glance.

Icons

An icon appears on the right side of the option, after the title, description, and chips. Icons work alongside every other content type, so an option can show an avatar on the left and an icon on the right.

Lazy loading options

For large datasets, options load on demand as users scroll through the list. Three pagination strategies are supported: page-based, offset-based, and group-based. Results are cached by default to avoid redundant requests.

Select All

Multi Select Field can include a Select All action at the top of the options list, allowing users to toggle all options at once. When combined with search filtering, the Select Filtered action selects only the currently visible results.

Field Options

Sizes

Three sizes are available: small, medium, and large. Choose a size that aligns with the surrounding form layout and density.

Prefix and suffix

Add content before or after the input to provide additional context, such as currency symbols or units.

Behavior

The Multi Select Field responds to user interaction with search filtering and distinct visual states.

Visual states

Multi Select Field supports standard form field states. Disabled prevents all interaction. Read-only allows viewing selected options without changing the selection. Error highlights validation issues with a message.

Max rows

The Select Field can grow in size to fit many selected options. A max row configuration limits how large the field can grow. Set a low max row count when space is tight, and a larger max row when displaying all the options is prioritized.

Usage Guidelines

Standard	Requirement
DoSelecting from a medium-to-large set	Select multiple options from a medium-to-large set of options
DoProviding typeahead search	Provide typeahead search to help users narrow results
DoLoading options from a server	Load options from a server with pagination support
DoOrganizing options into groups	Organize options into groups or pinned sections
DoProviding a Select All action	Provide a Select All action to toggle all options at once
DoDisplaying selected values as chips	Display selected values as removable chips
Don’tA single item to be selected	There is only a single item to be selected. Use Select Field instead.

Alternatives

When there are only a few items to choose from, a checkbox group may be more appropriate. When a particularly complex selection interaction is needed, a Listbox in a special layout may be preferred.

Multi Select Field vs Combobox

Multi Select Field is the eventual replacement for the Combobox component. Use Select Field when looking for features such as Dialog viewing, standardized content display, secondary actions, sectioning, or lazy loading. Consider using the Combobox if needing a stable component in your application.

Multi Select Field vs Select Trigger

MultiSelect Field displays options in a built-in Popover or Dialog with integrated search and filtering. Select Trigger opens a custom overlay — typically a Dialog — that the implementor fully controls.

How to Use

Labels and help

For guidance on labels, placeholders, and help text, refer to the Form pattern.

Sorting options

Multi Select Field does not prescribe how options are sorted. Common sorting strategies include alphabetical, time-based, and categorical. Choose a sort order that matches user expectations for the data.

Content

Content within the Multi Select Field should clearly communicate available options and help users identify the correct selections.

Use clear, concise option labels that users recognize immediately
Add descriptions to rich content options when labels alone are insufficient to distinguish items
Use pinned sections to surface frequently used or contextually relevant options

For additional content guidance, refer to the Form pattern.

Keyboard Interaction

Users can navigate the Multi Select Field using standard keyboard controls. Keyboard behavior differs between combobox mode (search enabled) and select mode (search disabled).

Search enabled

Text field

Key	Interaction
Down Arrow	If the listbox is displayed, moves visual focus to the first option. If the listbox is not displayed, opens it and moves visual focus to the first option. DOM focus remains on the text field.
Up Arrow	If the listbox is displayed, moves visual focus to the last option. If the listbox is not displayed, opens it and moves visual focus to the last option. DOM focus remains on the text field.
Enter	Toggles the selection state of the focused option.
Escape	If the listbox is displayed, closes it. If the listbox is not displayed, clears the text field.

Key	Interaction
Enter	Toggles the selection state of the focused option.
Escape	Closes the popup and returns visual focus to the text field.
Down Arrow	Moves visual focus to the next option. Wraps from last to first.
Up Arrow	Moves visual focus to the previous option. Wraps from first to last.

Search disabled

Key	Interaction
Enter / Space	Opens the listbox.
Down Arrow	Opens the listbox and moves focus to the first option.
Up Arrow	Opens the listbox and moves focus to the last option.
Escape	Closes the listbox.

Accessibility

Anvil provides accessibility support for Multi Select Field out of the box. In combobox mode, the component follows the combobox ARIA pattern. In select mode, it follows the listbox ARIA pattern. For more guidance on building accessible form controls, see custom component best practices.

Code

Implementation
MultiSelectField Props
MultiSelectFieldSync Props
MultiSelectFieldOption Type

Overview

The multi-select field family includes two components for different use cases:

MultiSelectField — For async data loading with support for pagination (page-based, offset-based, or group-based lazy loading)
- Includes automatic debouncing of the search input (configurable via the debounceMs prop)
- Includes automatic caching of the search input (configurable via the cache prop)
MultiSelectFieldSync — For client-side filtering of static option arrays

Both components provide a searchable dropdown interface for selecting multiple options, displaying selected values as chips with adaptive display modes (popover or dialog).

MultiSelectFieldSync (Static Options)

Use MultiSelectFieldSync when you have a static list of options that can be filtered client-side.

import { useState } from "react";
import { MultiSelectFieldSync } from "@servicetitan/anvil2";

const options = [
  { id: 1, label: "Option One" },
  { id: 2, label: "Option Two" },
  { id: 3, label: "Option Three" },
];

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);

  return (
    <MultiSelectFieldSync
      label="Select options"
      placeholder="Search options..."
      options={options}
      value={selectedOptions}
      onSelectedOptionsChange={setSelectedOptions}
    />
  );
};

Filtering and Sorting

By default, MultiSelectFieldSync uses match-sorter to filter options by their label and searchText fields. Results are also ranked by match quality, so the best matches appear first. Before any search is performed, options appear in the order they are supplied. You can customize this behavior in two ways:

Using match-sorter options

Pass a match-sorter options object to customize the default filtering and sorting behavior (e.g., change which keys are matched or adjust ranking):

<MultiSelectFieldSync
  options={options}
  filter={{
    keys: ["label", "searchText"],
    // ...other match-sorter options
  }}
  // ...other props
/>

Using a custom filter function

Pass a function for full control over both filtering and sort order. The returned array determines the exact order options appear in the dropdown:

<MultiSelectFieldSync
  options={options}
  filter={(options, searchValue) => {
    return options.filter((option) =>
      option.label?.toLowerCase().includes(searchValue.toLowerCase())
    );
  }}
  // ...other props
/>

MultiSelectField (Async Loading)

Use MultiSelectField when options need to be fetched from an API or when dealing with large datasets that require server-side filtering.

Basic Usage

import { useState } from "react";
import { MultiSelectField } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);

  return (
    <MultiSelectField
      label="Select Tags"
      placeholder="Search tags..."
      loadOptions={async (searchValue) => {
        const response = await fetch(`/api/tags?q=${searchValue}`);
        const tags = await response.json();
        return tags.map((tag) => ({
          id: tag.id,
          label: tag.name,
        }));
      }}
      value={selectedOptions}
      onSelectedOptionsChange={setSelectedOptions}
    />
  );
};

Lazy Loading Modes

MultiSelectField supports three lazy loading modes for paginated data:

Page-based Pagination

<MultiSelectField
  lazy="page"
  lazyOptions={{ pageSize: 10 }}
  loadOptions={async (searchValue, pageNumber, pageSize) => {
    const response = await fetch(
      `/api/items?q=${searchValue}&page=${pageNumber}&size=${pageSize}`
    );
    const { data, totalCount } = await response.json();
    return {
      options: data.map((item) => ({ id: item.id, label: item.name })),
      hasMore: pageNumber * pageSize + data.length < totalCount,
    };
  }}
  // ...other props
/>

Offset-based Pagination

<MultiSelectField
  lazy="offset"
  lazyOptions={{ limit: 15 }}
  loadOptions={async (searchValue, offset, limit) => {
    const response = await fetch(
      `/api/items?q=${searchValue}&offset=${offset}&limit=${limit}`
    );
    const { data, totalCount } = await response.json();
    return {
      options: data.map((item) => ({ id: item.id, label: item.name })),
      hasMore: offset + limit < totalCount,
    };
  }}
  // ...other props
/>

Group-based Loading

For loading grouped options incrementally:

<MultiSelectField
  lazy="group"
  groupToString={(groupValue) => String(groupValue)}
  loadOptions={async (searchValue, previousGroupKey) => {
    const response = await fetch(
      `/api/items?q=${searchValue}&afterGroup=${previousGroupKey || ""}`
    );
    const { data, hasMore } = await response.json();
    return {
      options: data.map((item) => ({
        id: item.id,
        label: item.name,
        group: item.category, // Required for grouped options
      })),
      hasMore,
    };
  }}
  // ...other props
/>

Select All

Enable bulk selection with the selectAll prop.

Select All is shown only when the search input is empty.

MultiSelectField

With MultiSelectField, the parent component is responsible for handling the select/deselect logic via onClick and managing the checkState:

import { useState } from "react";
import { MultiSelectField } from "@servicetitan/anvil2";

const allOptions = [
  { id: 1, label: "Option One" },
  { id: 2, label: "Option Two" },
  { id: 3, label: "Option Three" },
];

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);

  const handleSelectAll = () => {
    if (selectedOptions.length === allOptions.length) {
      setSelectedOptions([]);
    } else {
      setSelectedOptions(allOptions);
    }
  };

  return (
    <MultiSelectField
      label="Select Items"
      loadOptions={async () => allOptions}
      value={selectedOptions}
      onSelectedOptionsChange={setSelectedOptions}
      selectAll={{
        label: "Select All Items",
        onClick: handleSelectAll,
        checkState:
          selectedOptions.length === allOptions.length
            ? "checked"
            : selectedOptions.length > 0
              ? "indeterminate"
              : "unchecked",
      }}
    />
  );
};

checkState also accepts a function of the current selection, which the field resolves for you. This keeps the checkbox in sync with the selection without recomputing it at the call site:

selectAll={{
  label: "Select All Items",
  onClick: handleSelectAll,
  checkState: (current) =>
    current.length === 0
      ? "unchecked"
      : current.length >= allOptions.length
        ? "checked"
        : "indeterminate",
}}

MultiSelectFieldSync

MultiSelectFieldSync provides a simplified selectAll prop. Click handling and check state are managed automatically:

// Enable with default label
<MultiSelectFieldSync
  label="Select Tags"
  options={options}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  selectAll
/>

// Enable with custom label
<MultiSelectFieldSync
  label="Select Tags"
  options={options}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  selectAll={{ label: "Select All Tags" }}
/>

// Enable with dynamic label based on check state
<MultiSelectFieldSync
  label="Select Tags"
  options={options}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  selectAll={{ label: (checked) => checked ? "Deselect All" : "Select All" }}
/>

Select Filtered

Enable selection of options matching the current search term with the selectFiltered prop. Select All and Select Filtered are mutually exclusive: Select All is shown when the search input is empty, and Select Filtered is shown when a search term is active. The default label dynamically includes the search term (e.g., Select items matching "appl").

MultiSelectField

With MultiSelectField, provide a function that receives the current searchValue and returns a config object with onClick, checkState, and an optional label. Since the function receives the search value, you can use it to filter options and compute the checked state inline:

import { useState } from "react";
import { MultiSelectField } from "@servicetitan/anvil2";

const allOptions = [
  { id: 1, label: "Apple" },
  { id: 2, label: "Apricot" },
  { id: 3, label: "Banana" },
  { id: 4, label: "Cherry" },
];

const filterBySearch = (searchValue: string) =>
  allOptions.filter((opt) =>
    opt.label.toLowerCase().includes(searchValue.toLowerCase()),
  );

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);
  const selectedIds = new Set(selectedOptions.map((o) => o.id));

  return (
    <MultiSelectField
      label="Fruits"
      loadOptions={async (searchValue) => filterBySearch(searchValue)}
      value={selectedOptions}
      onSelectedOptionsChange={setSelectedOptions}
      selectFiltered={(searchValue) => {
        const filtered = filterBySearch(searchValue);
        const allFilteredSelected =
          filtered.length > 0 &&
          filtered.every((o) => selectedIds.has(o.id));
        const someFilteredSelected = filtered.some((o) =>
          selectedIds.has(o.id),
        );
        return {
          onClick: () => {
            if (allFilteredSelected) {
              const filteredIds = new Set(filtered.map((o) => o.id));
              setSelectedOptions(
                selectedOptions.filter((o) => !filteredIds.has(o.id)),
              );
            } else {
              const merged = [...selectedOptions];
              for (const opt of filtered) {
                if (!selectedIds.has(opt.id)) merged.push(opt);
              }
              setSelectedOptions(merged);
            }
          },
          checkState: allFilteredSelected
            ? "checked"
            : someFilteredSelected
              ? "indeterminate"
              : "unchecked",
        };
      }}
    />
  );
};

MultiSelectFieldSync

MultiSelectFieldSync provides a simplified selectFiltered prop. Click handling and check state are managed automatically based on the filtered options and current selection:

// Enable with default dynamic label
<MultiSelectFieldSync
  label="Fruits"
  options={options}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  selectFiltered
/>

// Enable with custom label based on search value
<MultiSelectFieldSync
  label="Fruits"
  options={options}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  selectFiltered={(searchValue) => ({
    label: `Select items matching "${searchValue}"`,
  })}
/>

// Combine with selectAll for full bulk selection
<MultiSelectFieldSync
  label="Fruits"
  options={options}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  selectAll
  selectFiltered
/>

Chip Display Options

Control how selected options are displayed as chips:

Single Row Mode

Restrict the field to a single row height. Overflow chips are collapsed into a “+N” indicator:

<MultiSelectField
  label="Tags"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  singleRow
/>

Max Chips

Limit the number of visible chips regardless of row height:

<MultiSelectField
  label="Tags"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  maxChips={5}
/>

Chip Customization

Customize the appearance of individual chips using getChipProps. The callback receives each selected option and returns partial ChipProps (e.g., color, icon, avatar). Core chip props (label, onClose, className, title, size) are managed by the component and excluded from the callback’s return type.

<MultiSelectField
  label="Users"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  getChipProps={(option) => ({
    color: option.id === "admin" ? "#e53935" : "#1e88e5",
    icon: PersonIcon,
  })}
/>

Display Modes

Control how the options menu is displayed using the displayMenuAs prop:

// Automatically choose based on device (default)
<MultiSelectField displayMenuAs="auto" {...props} />

// Always show as popover (not recommended for mobile)
<MultiSelectField displayMenuAs="popover" {...props} />

// Always show as dialog
<MultiSelectField displayMenuAs="dialog" {...props} />

Caching

MultiSelectField caches loadOptions results by default. Configure caching behavior:

// Disable caching
<MultiSelectField cache={{ enabled: false }} {...props} />

// Configure max cache size (default: 15)
<MultiSelectField cache={{ maxSize: 100 }} {...props} />

Clearing the Cache

Use a ref to imperatively clear the cache:

import { useRef } from "react";
import { MultiSelectField } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  const multiSelectRef = useRef(null);

  const handleRefresh = () => {
    multiSelectRef.current?.clearCache();
  };

  return (
    <>
      <MultiSelectField ref={multiSelectRef} {...props} />
      <button onClick={handleRefresh}>Refresh Options</button>
    </>
  );
};

Invalidating Options

Call invalidate() to clear the cache and reload options from the data source. Use this when the underlying data has changed and the component needs to reflect the update:

import { useRef } from "react";
import { MultiSelectField } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  const multiSelectRef = useRef(null);

  const handleDataSourceChange = () => {
    multiSelectRef.current?.invalidate();
  };

  return (
    <MultiSelectField ref={multiSelectRef} {...props} />
  );
};

MultiSelectFieldSync handles this automatically when its options prop changes.

Initial Load Behavior

Control when options are first loaded with the initialLoad prop:

// Load immediately on mount (default)
<MultiSelectField initialLoad="immediate" {...props} />

// Load when user opens the dropdown
<MultiSelectField initialLoad="open" {...props} />

// Auto (currently equivalent to "immediate")
<MultiSelectField initialLoad="auto" {...props} />

Field States

Error State

Display validation errors using the error prop:

<MultiSelectField
  label="Categories"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  error={selectedOptions.length === 0 ? "Please select at least one category" : false}
/>

Hint and Description

Provide additional context with hint and description:

<MultiSelectField
  label="Categories"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  hint="Select up to 5 categories"
  description="These will be used for filtering"
/>

Required Field

Mark a field as required with the required prop:

<MultiSelectField
  label="Categories"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  required
/>

Disabled and ReadOnly

When disabled is set, users cannot interact with the field:

<MultiSelectField
  label="Categories"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  disabled
/>

When readOnly is set, users can see the dropdown but cannot change selections:

<MultiSelectField
  label="Categories"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  readOnly
/>

Prefix and Suffix

Add content before or after the input with prefix and suffix:

<MultiSelectField
  label="Tags"
  loadOptions={loadOptions}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
  prefix="#"
  suffix="tags"
/>

Markdown in labels

The label prop supports inline markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`).

Hide the label

Use hideLabel to visually hide the label. The label string is converted to an aria-label on the input so it remains accessible to screen readers — any inline markdown is stripped to plain text.

Sizes

Control the size of the field with the size prop:

<MultiSelectField size="small" {...props} />
<MultiSelectField size="medium" {...props} /> {/* default */}
<MultiSelectField size="large" {...props} />

Disabled Options

Individual options can be disabled by setting disabled: true on the option:

const options = [
  { id: 1, label: "Available Option" },
  { id: 2, label: "Unavailable Option", disabled: true },
  { id: 3, label: "Another Available Option" },
];

<MultiSelectField
  label="Select options"
  loadOptions={async () => options}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
/>

Pinned Options

Pin frequently used or suggested options above the list using the pinned prop. Each pinned section requires a label and an options value, which can be a static array or a dynamic loader function.

Static Pinned Options

Pass an object with label and a static options array:

<MultiSelectField
  label="Books"
  pinned={{
    label: "Favorites",
    options: [
      { id: "fav-1", label: "The Martian" },
      { id: "fav-2", label: "Dune" },
    ],
  }}
  loadOptions={fetchBooks}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
/>

Dynamic Pinned Options

Pass a function as options to compute pinned options based on the current search value. This is useful for AI-powered suggestions or context-aware recommendations:

<MultiSelectField
  label="Books"
  pinned={{
    label: "AI Suggestions",
    options: async (searchValue) => {
      const suggestions = await fetchAISuggestions(searchValue);
      return suggestions.map((s) => ({ id: s.id, label: s.title }));
    },
  }}
  loadOptions={fetchBooks}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
/>

By default, the loader re-runs whenever the search value changes. Set searchReactive: false to call the loader once and reuse the result across all search values:

<MultiSelectField
  label="Books"
  pinned={{
    label: "Your Favorites",
    options: async () => {
      return await fetchFavorites();
    },
    searchReactive: false,
  }}
  loadOptions={fetchBooks}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
/>

Multiple Pinned Sections

Pass an array of pinned section objects:

<MultiSelectField
  label="Books"
  pinned={[
    {
      label: "AI Suggestions",
      options: async (searchValue) => {
        const suggestions = await fetchAISuggestions(searchValue);
        return suggestions.map((s) => ({ id: s.id, label: s.title }));
      },
    },
    {
      label: "Your Favorites",
      options: [
        { id: "fav-1", label: "Dune" },
        { id: "fav-2", label: "Foundation" },
      ],
    },
  ]}
  loadOptions={fetchBooks}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
/>

Grouping Options

Options can be organized into visual groups by adding a group property to each option. Groups appear as labeled sections in the dropdown.

Basic Grouping

Add a group property to options and provide a groupToString function to display group labels:

const options = [
  { id: 1, label: "Apple", group: "fruits" },
  { id: 2, label: "Banana", group: "fruits" },
  { id: 3, label: "Carrot", group: "vegetables" },
  { id: 4, label: "Broccoli", group: "vegetables" },
];

<MultiSelectField
  label="Food"
  loadOptions={async () => options}
  groupToString={(group) =>
    group === "fruits" ? "Fruits" : "Vegetables"
  }
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
/>

Group Sorting

Use groupSorter to control the order of groups. By default, groups appear in the order they are first encountered in the options array. This prop is available on MultiSelectFieldSync and non-lazy MultiSelectField:

Avoid using groupSorter with lazy="group". When groups load incrementally from the server and get re-sorted, the menu content shifts unexpectedly, creating a disorienting user experience. Instead, have your server return groups in the desired order.

const options = [
  { id: 1, label: "Item A", group: 3 },
  { id: 2, label: "Item B", group: 1 },
  { id: 3, label: "Item C", group: 2 },
];

<MultiSelectField
  label="Items"
  loadOptions={async () => options}
  groupToString={(group) => `Priority ${group}`}
  groupSorter={(a, b) => Number(a) - Number(b)}
  value={selectedOptions}
  onSelectedOptionsChange={setSelectedOptions}
/>

Virtualization

By default, all dropdown options render to the DOM at once. This works well for typical lists but degrades performance with very large option sets as the browser must lay out and paint thousands of elements. Pass virtualize to enable windowed rendering, which only renders the items currently visible in the scroll viewport plus a small overscan buffer.Consider enabling virtualize when the dropdown feels sluggish to open or keyboard navigation becomes laggy. These symptoms typically appear around 200–500 items depending on device performance and item complexity (e.g., items with descriptions are heavier). For smaller lists, the default rendering path is sufficient and avoids the overhead of virtual positioning.Virtualization works with all existing features including lazy loading, pinned options, grouping, select-all/select-filtered bulk actions, and keyboard navigation.

import { useState } from "react";
import { MultiSelectFieldSync } from "@servicetitan/anvil2";

const options = Array.from({ length: 5000 }, (_, i) => ({
  id: i,
  label: `Option ${i + 1}`,
}));

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);

  return (
    <MultiSelectFieldSync
      virtualize
      selectAll
      label="Large dataset"
      placeholder="Search options..."
      options={options}
      value={selectedOptions}
      onSelectedOptionsChange={setSelectedOptions}
    />
  );
};

Disabling Search

Pass disableSearch to replace the searchable text input with a non-editable select trigger. The field uses the listbox ARIA pattern instead of combobox, providing a simpler interaction when typing to filter adds no value.This is useful when the option list is short and well-known or you are integrating with an API that does not support search.

import { useState } from "react";
import { MultiSelectFieldSync } from "@servicetitan/anvil2";

const options = [
  { id: 1, label: "Red" },
  { id: 2, label: "Green" },
  { id: 3, label: "Blue" },
  { id: 4, label: "Yellow" },
];

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);

  return (
    <MultiSelectFieldSync
      disableSearch
      selectAll
      label="Colors"
      placeholder="Select colors"
      options={options}
      value={selectedOptions}
      onSelectedOptionsChange={setSelectedOptions}
    />
  );
};

When disableSearch is enabled, selectFiltered has no effect since there is no search input to produce filtered results.

Adding New Items

Provide an onAddNewItem handler to render an “Add new item” button below the option list. This affordance lets users create a value that does not exist yet — a new tag, label, or attribute — quickly from the field.The button sits in a footer region inside the menu. Clicking or activating it via keyboard closes the menu and invokes the onAddNewItem handler with the current search text.From here, it is your responsibility to launch a Dialog (or Drawer, or any other overlay) for collecting the new item’s details, append the result to the option source, invalidate the cache, and update selection state.You may pair onAddNewItem with addItemLabel to control the button text. The label accepts a static node or a function of the current search text — for example, returning Add "foo" when the user has typed foo.When addItemLabel is a function, return null (or undefined) to hide the button for the current search text. Use this when the affordance should only appear for valid input — for example, showing “Add email” only after a well-formed address is typed:

addItemLabel={(searchText) =>
  isValidEmail(searchText) ? `Add "${searchText}"` : null
}
onAddNewItem={openAddEmailDialog}

Call invalidate() on the imperative handle after appending the new option. This clears the cached search results and forces a refetch the next time the menu opens, so the new item appears immediately. clearCache() alone wipes the cache but keeps the previously displayed options on screen until something else triggers a reload.

Testing

The field’s interactive sub-elements carry a stable data-anv-part attribute so end-to-end tests can target them directly. The library owns the part names; you supply the instance identifier.Attach your own data-* attribute (such as data-cy or data-testid) to the field. It is forwarded to the field’s wrapper element, letting you scope queries to a single instance:

<MultiSelectField data-cy="tag-picker" label="Tags" {...rest} />

// Target the input within this specific field
cy.get('[data-cy="tag-picker"] [data-anv-part="input"]').type("urgent");

// Assert the number of selected-value chips
cy.get('[data-cy="tag-picker"] [data-anv-part="chip"]').should("have.length", 2);

`data-anv-part`	Element
`input`	Text input (searchable mode)
`trigger`	Trigger element (`disableSearch` mode)
`chip`	A selected-value chip
`overflow-chip`	”+N” indicator when selected chips overflow
`clear-button`	Button that clears the selection
`toggle-button`	Button that opens and closes the menu
`menu`	Option list container
`option`	An individual option row
`dialog`	Menu container in dialog display mode
`popover`	Menu container in popover display mode

The menu renders in the browser’s top layer (menu, option, dialog, and popover parts), outside the field’s wrapper. Descendant queries scoped to your wrapper attribute will not match these parts. Target them by their part attribute directly, or scope to the menu’s id — #{id}-popover or #{id}-dialog, where {id} is the field’s id prop. Only one menu is open at a time.

`MultiSelectField` Props

import { useState } from "react";
import { MultiSelectField } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);

  return (
    <MultiSelectField
      label="Search users"
      loadOptions={async (searchValue) => {
        const response = await fetch(`/api/users?q=${searchValue}`);
        const users = await response.json();
        return users.map((user) => ({
          id: user.id,
          label: user.name,
        }));
      }}
      onSelectedOptionsChange={setSelectedOptions}
      value={selectedOptions}
    />
  );
};

string

required

The label of the multi-select field. Supports inline markdown formatting.

boolean | AiMarkWithTooltipOrPopoverConfig

Displays an AI mark next to the label. Use true for the icon only, or pass tooltip or popover configuration. See AI Marks.

function

required

Function to load options. The signature depends on the lazy mode:

Non-lazy: (searchValue: string) => MultiSelectFieldOption[] | Promise<MultiSelectFieldOption[]>
Page-based: (searchValue: string, pageNumber: number, pageSize: number) => { options: MultiSelectFieldOption[], hasMore?: boolean }
Offset-based: (searchValue: string, offset: number, limit: number) => { options: MultiSelectFieldOption[], hasMore?: boolean }
Group-based: (searchValue: string, previousGroupKey: string | number | null) => { options: MultiSelectFieldGroupedOption[], hasMore?: boolean }

(options: MultiSelectFieldOption[]) => void

required

Callback fired when the selected options change. Receives the new array of selected options.

MultiSelectFieldOption[]

required

The currently selected options. Must be controlled state.

ReactNode | (searchText: string) => ReactNode

Label rendered inside the “Add new item” button. May be a static node or a callback that receives the current search text and returns a dynamic label (for example, Add "${searchText}"). When the callback returns null or undefined, the button is not rendered — use this to hide the affordance until the search text is valid (for example, a well-formed email). Defaults to "Add new item" when omitted but onAddNewItem is provided.

MultiSelectFieldCacheOptions

Configuration for caching loadOptions results:

enabled — Whether caching is enabled (default: true)
maxSize — Maximum number of search values to cache before clearing (default: 15)

string

Custom CSS class name for the wrapper element.

number

default:"200"

Milliseconds to debounce search input before calling loadOptions.

ReactElement | string

Description text displayed below the input field.

boolean

default:"false"

Replaces the searchable text input with a non-editable select trigger. Uses the listbox ARIA pattern instead of combobox. When combined with displayMenuAs="dialog", the search input in the dialog header is also removed. The selectAll bulk action remains available; selectFiltered has no effect.

boolean

default:"false"

Whether the field is disabled. When disabled, the field cannot be interacted with and the dropdown cannot open.

How to display the options menu:

auto — Popover on desktop, dialog on mobile
popover — Always display as popover
dialog — Always display as dialog

ReactElement | string | boolean

Error state for the field. When true, shows error styling. When a string or ReactElement, also displays as an error message below the field.

'off' | 'assertive' | 'polite'

default:"assertive"

Controls the aria-live behavior for error messages. See MDN docs.

(a: MultiSelectFieldGroupByValue, b: MultiSelectFieldGroupByValue) => number

Function to compare two group values for sorting. When provided, groups are sorted using this comparator. Without this, groups appear in the order they are first encountered. Best used with MultiSelectFieldSync or non-lazy MultiSelectField. Avoid using with lazy="group" as it causes the menu to shift unexpectedly when new groups load.

(option: MultiSelectFieldOption) => MultiSelectFieldChipProps

Callback to customize chip appearance for each selected option. Returns partial chip props such as color, icon, or avatar. Core props (label, onClose, className, title, size) are managed by the component and excluded from this type.

(groupValue: MultiSelectFieldGroupByValue) => string

Function to convert group values to display labels. Only used with grouped options. MultiSelectFieldGroupByValue is string | number.

boolean

default:"false"

Visually hides the label above the input while keeping it accessible to screen readers. Note: This does not affect the label displayed in the adaptive dialog view on mobile devices.

ReactElement | string

Hint text displayed below the input field.

string

The id of the multi-select field.

'auto' | 'immediate' | 'open'

default:"auto"

Controls when loadOptions is first called:

auto — Currently equivalent to immediate
immediate — Load on component mount
open — Load when dropdown is opened

boolean

default:"false"

When true, applies a subdued primary background to draw attention to the field.

'page' | 'offset' | 'group' | false

default:"false"

Enables lazy loading with the specified pagination strategy.

object

Configuration for lazy loading:

Page mode: { pageSize?: number } (default pageSize: 20)
Offset mode: { limit?: number } (default limit: 20)
Group mode: {}

number

default:"10"

Maximum number of chips to display before showing a “+N” indicator. Applies regardless of singleRow setting.

ReactNode

Additional information displayed in a tooltip next to the label. Renders an info icon button that shows the content on hover or focus.

(searchText: string) => void

Click handler for the “Add new item” button. The button is only rendered when this prop is provided. Receives the current search text. The menu closes synchronously on click and the handler runs immediately after — typically opening a Dialog or Drawer to collect the new item’s details. Consumers own overlay presentation, focus return, option list updates, and selection state. See the Adding New Items section for a full example.

MultiSelectFieldPinnedOptions

Options to pin to the top of the list. Accepts a single section object or an array of section objects. Each section requires:

label — Display label for the section header
options — Static array (MultiSelectFieldOption[]) or dynamic loader function ((searchValue: string) => MultiSelectFieldOption[] | Promise<MultiSelectFieldOption[]>)
searchReactive — (Optional) Whether to re-call the loader when the search value changes. Defaults to true. Set to false to call the loader once and reuse the result.
cacheSize — (Optional) Maximum number of search results to cache per section. Defaults to 15. Only applies when searchReactive is true.

string

Placeholder text for the input field.

string | ReactElement

Content to display before the input field.

boolean

default:"false"

Whether the field is read-only. When read-only, the dropdown can open to view options but selections cannot be changed.

boolean

default:"false"

Whether the field is required. Shows a red asterisk (*) next to the label.

BulkActionConfig

Configuration for the “Select All” option. Pass exactly one of onClick or compute:

label — The label to display (default: “Select All”)
onClick — Callback when clicked. Parent component commits the next selection via onSelectedOptionsChange.
compute(current) => next | Promise<next> — The field invokes compute with the current selection and commits the returned array. While a returned promise is pending, the row shows a loading state, option rows are disabled, and stale resolutions are discarded.
checkState — State: true/"checked", false/"unchecked", or "indeterminate". Also accepts a function (current: SelectFieldOption[]) => boolean | CheckState that derives the state from the current selection.

(searchValue: string) => BulkActionConfig

Function that receives the current search value and returns configuration for the “Select Filtered” option (mutually exclusive with selectAll, shown when a search term is active). Accepts the same onClick / compute choice as selectAll:

label — The label to display. Default: Select items matching "${searchValue}"
onClick or compute — See selectAll above.
checkState — State: true/"checked", false/"unchecked", or "indeterminate". Also accepts a function (current: SelectFieldOption[]) => boolean | CheckState that derives the state from the current selection.

boolean

default:"false"

When true, restricts the field to a single row height. Overflow chips collapse into a “+N” indicator.

'small' | 'medium' | 'large'

The size of the multi-select field.

CSSProperties

Custom inline styles for the wrapper element.

string | ReactElement

Content to display after the input field.

boolean

default:"false"

Enables windowed rendering for the dropdown list. Improves performance for large option sets by only rendering visible items. Consider enabling when the dropdown feels sluggish to open or keyboard navigation becomes laggy, typically around 200–500+ items.

`MultiSelectFieldSync` Props

MultiSelectFieldSync accepts all props from MultiSelectField except loadOptions, lazy, debounceMs, cache, and initialLoad, plus the following:

import { useState } from "react";
import { MultiSelectFieldSync } from "@servicetitan/anvil2";

const options = [
  { id: 1, label: "Option One" },
  { id: 2, label: "Option Two" },
  { id: 3, label: "Option Three" },
];

const ExampleComponent = () => {
  const [selectedOptions, setSelectedOptions] = useState([]);

  return (
    <MultiSelectFieldSync
      label="Select options"
      onSelectedOptionsChange={setSelectedOptions}
      options={options}
      value={selectedOptions}
    />
  );
};

string

required

The label of the multi-select field. Supports inline markdown formatting.

boolean | AiMarkWithTooltipOrPopoverConfig

Displays an AI mark next to the label. Use true for the icon only, or pass tooltip or popover configuration. See AI Marks.

(options: MultiSelectFieldOption[]) => void

required

Callback fired when the selected options change. Receives the new array of selected options.

MultiSelectFieldOption[]

required

The array of options to display in the multi-select field.

MultiSelectFieldOption[]

required

The currently selected options. Must be controlled state.

ReactNode | (searchText: string) => ReactNode

string

Custom CSS class name for the wrapper element.

ReactElement | string

Description text displayed below the input field.

boolean

default:"false"

boolean

default:"false"

Whether the field is disabled. When disabled, the field cannot be interacted with and the dropdown cannot open.

How to display the options menu.

ReactElement | string | boolean

Error state for the field. When true, shows error styling. When a string or ReactElement, also displays as an error message below the field.

'off' | 'assertive' | 'polite'

default:"assertive"

Controls the aria-live behavior for error messages.

function | MatchSorterOptions

Controls how options are filtered and sorted when the user types a search value. Can be:

A function: (options: MultiSelectFieldOption[], searchValue: string) => MultiSelectFieldOption[] — receives all options and returns the filtered subset in the desired display order
A match-sorter options object to customize the default match-sorter behavior (e.g., which keys to match against, ranking strategy)

Before any search is performed, options appear in the order they are supplied. Default: Filters by label and searchText fields using match-sorter, with results ranked by match quality.

(a: MultiSelectFieldGroupByValue, b: MultiSelectFieldGroupByValue) => number

Function to compare two group values for sorting. When provided, options are sorted by group using this comparator, then by match-sort order within each group. Ungrouped options appear last.

(option: MultiSelectFieldOption) => MultiSelectFieldChipProps

(groupValue: MultiSelectFieldGroupByValue) => string

Function to convert group values to display labels. Only used with grouped options. MultiSelectFieldGroupByValue is string | number.

boolean

default:"false"

Visually hides the label above the input while keeping it accessible to screen readers. Note: This does not affect the label displayed in the adaptive dialog view on mobile devices.

ReactElement | string

Hint text displayed below the input field.

string

The id of the multi-select field.

number

default:"10"

Maximum number of chips to display before showing a “+N” indicator.

ReactNode

Additional information displayed in a tooltip next to the label. Renders an info icon button that shows the content on hover or focus.

(searchText: string) => void

MultiSelectFieldPinnedOptions

Options to pin to the top of the list. Accepts the same section object format as MultiSelectField’s pinned prop.

string

Placeholder text for the input field.

string | ReactElement

Content to display before the input field.

boolean

default:"false"

Whether the field is read-only. When read-only, the dropdown can open to view options but selections cannot be changed.

boolean

default:"false"

Whether the field is required. Shows a red asterisk (*) next to the label.

boolean | { label?: string | ((checked: boolean) => string) }

Enables the “Select All” option at the top of the list. Can be:

true — Enable with default label “Select All”
{ label: "Custom Label" } — Enable with custom static label
{ label: (checked) => checked ? "Deselect All" : "Select All" } — Enable with dynamic label based on check state

Click handling and check state are managed automatically based on comparing options with value.

boolean | (searchValue: string) => { label?: string }

Enables the “Select Filtered” option when a search term is active (mutually exclusive with selectAll). Can be:

true — Enable with default dynamic label
(searchValue) => ({ label }) — A function that receives the search value and returns a config with an optional custom label

Click handling and check state are managed automatically based on comparing filtered options with value.

boolean

default:"false"

When true, restricts the field to a single row height. Overflow chips collapse into a “+N” indicator.

'small' | 'medium' | 'large'

The size of the multi-select field.

CSSProperties

Custom inline styles for the wrapper element.

string | ReactElement

Content to display after the input field.

boolean

default:"false"

`MultiSelectFieldOption` Type

Options passed to or returned from MultiSelectField must conform to this shape:

type MultiSelectFieldOption = {
  /** Unique identifier for the option */
  id: string | number;

  /** Display text for the option */
  label: string;

  /** Optional text used for search matching (in addition to label) */
  searchText?: string;

  /** Group key for grouped options (required when using lazy="group") */
  group?: string | number;

  /** Whether the option is disabled and cannot be selected */
  disabled?: boolean;

  /** Optional rich content configuration */
  content?: {
    title?: string;
    description?: string;
    chips?: Pick<ChipProps, "label" | "color" | "textWrap">[];
    avatar?: Pick<AvatarProps, "name" | "status" | "color" | "image">;
    icon?: Pick<IconProps, "svg" | "color">;
  };
};

Content Properties

The content object supports the following optional properties:

title — Replaces the label as the primary display text in the dropdown.
description — Secondary text displayed below the title.
chips — Array of chip configurations rendered below the title and description. Each chip accepts label, color, and textWrap.
avatar — Renders an avatar to the left of the option text. Accepts name, status, color, and image.
icon — Renders an icon to the right of the option text. Accepts svg and color.

Example with Rich Content

const options: MultiSelectFieldOption[] = [
  {
    id: 1,
    label: "John Doe",
    searchText: "john.doe@example.com",
    content: {
      title: "John Doe",
      description: "Engineering",
    },
  },
  {
    id: 2,
    label: "Jane Smith",
    searchText: "jane.smith@example.com",
    content: {
      title: "Jane Smith",
      description: "Design",
    },
  },
];

Example with Avatar, Icon, and Chips

import GroupIcon from "@servicetitan/anvil2/assets/icons/material/round/groups.svg";

const options: MultiSelectFieldOption[] = [
  {
    id: 1,
    label: "Anvil Team",
    content: {
      title: "Anvil Team (4)",
      description: "Design system maintainer",
      icon: { svg: GroupIcon },
    },
  },
  {
    id: 2,
    label: "Ergonomic Chair",
    content: {
      title: "Ergonomic Chair",
      description: "Offers support and breathability",
      avatar: { name: "Ergonomic Chair", image: "/images/chair.png" },
      chips: [
        { label: "In Stock" },
        { label: "Popular", color: "#F97316" },
      ],
    },
  },
];

Example with Grouped Options

When using lazy="group", options must include the group property:

const groupedOptions: MultiSelectFieldOption[] = [
  {
    id: 1,
    label: "John Doe",
    group: "Engineering",
  },
  {
    id: 2,
    label: "Jane Smith",
    group: "Design",
  },
  {
    id: 3,
    label: "Bob Johnson",
    group: "Engineering",
  },
];

Example with Disabled Options

const options: MultiSelectFieldOption[] = [
  {
    id: 1,
    label: "Available Option",
  },
  {
    id: 2,
    label: "Unavailable Option",
    disabled: true,
  },
  {
    id: 3,
    label: "Another Available Option",
  },
];

​Anatomy

​Options

​Selection options

​Search

​Select-only

​Menu display options

​In a Popover

​In a Dialog

​Sections

​Pinned sections

​Rich content

​Icons

​Lazy loading options

​Select All

​Field Options

​Sizes

​Prefix and suffix

​Behavior

​Visual states

​Max rows

​Usage Guidelines

​Alternatives

​Multi Select Field vs Combobox

​Multi Select Field vs Select Trigger

​How to Use

​Labels and help

​Sorting options

​Content

​Keyboard Interaction

​Search enabled

​Text field

​Popup

​Search disabled

​Accessibility

​Code

​Overview

​MultiSelectFieldSync (Static Options)

​Filtering and Sorting

​Using match-sorter options

​Using a custom filter function

​MultiSelectField (Async Loading)

​Basic Usage

​Lazy Loading Modes

​Page-based Pagination

​Offset-based Pagination

​Group-based Loading

​Select All

​MultiSelectField

​MultiSelectFieldSync

​Select Filtered

​MultiSelectField

​MultiSelectFieldSync

​Chip Display Options

​Single Row Mode

​Max Chips

​Chip Customization

​Display Modes

​Caching

​Clearing the Cache

​Invalidating Options

​Initial Load Behavior

​Field States

​Error State

​Hint and Description

​Required Field

​Disabled and ReadOnly

​Prefix and Suffix

​Markdown in labels

​Hide the label

​Sizes

​Disabled Options

​Pinned Options

​Static Pinned Options

​Dynamic Pinned Options

​Multiple Pinned Sections

​Grouping Options

​Basic Grouping

​Group Sorting

​Virtualization

​Disabling Search

Anatomy

Options

Selection options

Search

Select-only

Menu display options

In a Popover

In a Dialog

Sections

Pinned sections

Rich content

Icons

Lazy loading options

Select All

Field Options

Sizes

Prefix and suffix

Behavior

Visual states

Max rows

Usage Guidelines

Alternatives

Multi Select Field vs Combobox

Multi Select Field vs Select Trigger

How to Use

Labels and help

Sorting options

Content

Keyboard Interaction

Search enabled

Text field

Popup

Search disabled

Accessibility

Code

Overview

MultiSelectFieldSync (Static Options)

Filtering and Sorting

Using match-sorter options

Using a custom filter function

MultiSelectField (Async Loading)

Basic Usage

Lazy Loading Modes

Page-based Pagination

Offset-based Pagination

Group-based Loading

Select All

MultiSelectField

MultiSelectFieldSync

Select Filtered

MultiSelectField

MultiSelectFieldSync

Chip Display Options

Single Row Mode

Max Chips

Chip Customization

Display Modes

Caching

Clearing the Cache

Invalidating Options

Initial Load Behavior

Field States

Error State

Hint and Description

Required Field

Disabled and ReadOnly

Prefix and Suffix

Markdown in labels

Hide the label

Sizes

Disabled Options

Pinned Options

Static Pinned Options

Dynamic Pinned Options

Multiple Pinned Sections

Grouping Options

Basic Grouping

Group Sorting

Virtualization

Disabling Search