;
}
};
**Beta Feature**
This feature is currently in beta, and needs to be imported from `@servicetitan/anvil2/beta`.
While we hope to minimize breaking changes, they may occur due to feedback we receive or other improvements. These will always be documented in the changelog and communicated in Slack.
Please reach out in the [#ask-designsystem](https://servicetitan.enterprise.slack.com/archives/CBSRGHTRS) channel with any questions or feedback!
## Overview
The multi-select menu family includes two components for different use cases:
* **`MultiSelectMenu`** — 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)
* **`MultiSelectMenuSync`** — For client-side filtering of static option arrays
Both components attach a searchable dropdown to any trigger element via a `trigger` render prop. The menu stays open after selecting an option, allowing multiple selections. Use `MultiSelectMenu` when you need multi-selection behavior outside of a form field context — for example, attaching a dropdown to a button, icon, or custom element.
Looking for a form field with a built-in label, error state, and chip display? Use [`MultiSelectField`](/docs/web/components/multi-select-field/code) instead.
## MultiSelectMenuSync (Static Options)
Use `MultiSelectMenuSync` when you have a static list of options that can be filtered client-side.
```tsx theme={null}
import { useState } from "react";
import { MultiSelectMenuSync } from "@servicetitan/anvil2/beta";
import { Button } 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 (
(
)}
/>
);
};
```
### Filtering and Sorting
By default, `MultiSelectMenuSync` uses [match-sorter](https://github.com/kentcdodds/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](https://github.com/kentcdodds/match-sorter#options) to customize the default filtering and sorting behavior (e.g., change which keys are matched or adjust ranking):
```tsx theme={null}
```
#### 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:
```tsx theme={null}
{
return options.filter((option) =>
option.label?.toLowerCase().includes(searchValue.toLowerCase())
);
}}
// ...other props
/>
```
## MultiSelectMenu (Async Loading)
Use `MultiSelectMenu` when options need to be fetched from an API or when dealing with large datasets that require server-side filtering.
### Basic Usage
```tsx theme={null}
import { useState } from "react";
import { MultiSelectMenu } from "@servicetitan/anvil2/beta";
import { Button } from "@servicetitan/anvil2";
const ExampleComponent = () => {
const [selectedOptions, setSelectedOptions] = useState([]);
return (
{
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}
trigger={(props) => (
)}
/>
);
};
```
### Lazy Loading Modes
`MultiSelectMenu` supports three lazy loading modes for paginated data:
#### Page-based Pagination
```tsx theme={null}
{
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
```tsx theme={null}
{
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:
```tsx theme={null}
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,
})),
hasMore,
};
}}
// ...other props
/>
```
## Select All
Enable bulk selection with the `selectAll` prop.
Select All is shown only when the search input is empty.
### MultiSelectMenu
With `MultiSelectMenu`, the parent component is responsible for handling the select/deselect logic via `onClick` and managing the `checkState`:
```tsx theme={null}
import { useState } from "react";
import { MultiSelectMenu } from "@servicetitan/anvil2/beta";
import { Button } 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 (
allOptions}
value={selectedOptions}
onSelectedOptionsChange={setSelectedOptions}
selectAll={{
label: "Select All Items",
onClick: handleSelectAll,
checkState:
selectedOptions.length === allOptions.length
? "checked"
: selectedOptions.length > 0
? "indeterminate"
: "unchecked",
}}
trigger={(props) => (
)}
/>
);
};
```
### MultiSelectMenuSync
`MultiSelectMenuSync` provides a simplified `selectAll` prop. Click handling and check state are managed automatically:
```tsx theme={null}
// Enable with default label
}
/>
// Enable with custom label
}
/>
// Enable with dynamic label based on check state
checked ? "Deselect All" : "Select All" }}
trigger={(props) => }
/>
```
## 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.
### MultiSelectMenu
With `MultiSelectMenu`, provide a function that receives the current `searchValue` and returns a config object with `onClick`, `checkState`, and an optional `label`:
```tsx theme={null}
import { useState } from "react";
import { MultiSelectMenu } from "@servicetitan/anvil2/beta";
import { Button } 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 (
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",
};
}}
trigger={(props) => (
)}
/>
);
};
```
### MultiSelectMenuSync
`MultiSelectMenuSync` provides a simplified `selectFiltered` prop. Click handling and check state are managed automatically based on the filtered options and current selection:
```tsx theme={null}
// Enable with default dynamic label
}
/>
// Enable with custom label based on search value
({
label: `Select items matching "${searchValue}"`,
})}
trigger={(props) => }
/>
// Combine with selectAll for full bulk selection
}
/>
```
## Display Modes
Control how the options menu is displayed using the `displayMenuAs` prop:
```tsx theme={null}
// Automatically choose based on device (default)
// Always show as popover (not recommended for mobile)
// Always show as dialog
```
## Popover Width
Control the width of the popover using the `width` prop:
```tsx theme={null}
// Fixed pixel width
// CSS string value
```
## Caching
`MultiSelectMenu` caches `loadOptions` results by default. Configure caching behavior:
```tsx theme={null}
// Disable caching
// Configure max cache size (default: 15)
```
### Clearing the Cache
Use a ref to imperatively clear the cache:
```tsx theme={null}
import { useRef } from "react";
import { MultiSelectMenu } from "@servicetitan/anvil2/beta";
const ExampleComponent = () => {
const multiSelectMenuRef = useRef(null);
const handleRefresh = () => {
multiSelectMenuRef.current?.clearCache();
};
return (
<>
);
};
```
### 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:
```tsx theme={null}
import { useRef } from "react";
import { MultiSelectMenu } from "@servicetitan/anvil2/beta";
const ExampleComponent = () => {
const multiSelectMenuRef = useRef(null);
const handleDataSourceChange = () => {
multiSelectMenuRef.current?.invalidate();
};
return (
);
};
```
`MultiSelectMenuSync` handles this automatically when its `options` prop changes.
## Initial Load Behavior
Control when options are first loaded with the `initialLoad` prop:
```tsx theme={null}
// Load immediately on mount (default for "auto")
// Load when user opens the dropdown
// Auto (currently equivalent to "immediate")
```
## Disabling Search
Pass `disableSearch` to remove the search input from inside the menu. The menu renders only the option list, and keyboard focus moves directly to the list container.
This is useful when the option list is short and well-known or you are integrating with an API that does not support search.
```tsx theme={null}
import { useState } from "react";
import { MultiSelectMenuSync } from "@servicetitan/anvil2/beta";
import { Button } 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 (
(
)}
/>
);
};
```
When `disableSearch` is enabled, `selectFiltered` has no effect since there is no search input to produce filtered results.
## Disabled Options
Individual options can be disabled by setting `disabled: true` on the option:
```tsx theme={null}
const options = [
{ id: 1, label: "Available Option" },
{ id: 2, label: "Unavailable Option", disabled: true },
{ id: 3, label: "Another Available Option" },
];
}
/>
```
## 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:
```tsx theme={null}
}
/>
```
### Dynamic Pinned Options
Pass a function as `options` to compute pinned options based on the current search value:
```tsx theme={null}
{
const suggestions = await fetchAISuggestions(searchValue);
return suggestions.map((s) => ({ id: s.id, label: s.title }));
},
}}
loadOptions={fetchBooks}
value={selectedOptions}
onSelectedOptionsChange={setSelectedOptions}
trigger={(props) => }
/>
```
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:
```tsx theme={null}
{
return await fetchFavorites();
},
searchReactive: false,
}}
loadOptions={fetchBooks}
value={selectedOptions}
onSelectedOptionsChange={setSelectedOptions}
trigger={(props) => }
/>
```
### Multiple Pinned Sections
Pass an array of pinned section objects:
```tsx theme={null}
{
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}
trigger={(props) => }
/>
```
## 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:
```tsx theme={null}
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" },
];
options}
groupToString={(group) =>
group === "fruits" ? "Fruits" : "Vegetables"
}
value={selectedOptions}
onSelectedOptionsChange={setSelectedOptions}
trigger={(props) => }
/>
```
### 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 `MultiSelectMenuSync` and non-lazy `MultiSelectMenu`:
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.
```tsx theme={null}
const options = [
{ id: 1, label: "Item A", group: 3 },
{ id: 2, label: "Item B", group: 1 },
{ id: 3, label: "Item C", group: 2 },
];
options}
groupToString={(group) => `Priority ${group}`}
groupSorter={(a, b) => Number(a) - Number(b)}
value={selectedOptions}
onSelectedOptionsChange={setSelectedOptions}
trigger={(props) => }
/>
```
## 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. 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.
Virtualization works with all existing features including lazy loading, pinned options, grouping, select-all/select-filtered bulk actions, and keyboard navigation.
```tsx theme={null}
import { useState } from "react";
import { MultiSelectMenuSync } from "@servicetitan/anvil2/beta";
import { Button } from "@servicetitan/anvil2";
const options = Array.from({ length: 5000 }, (_, i) => ({
id: i,
label: `Option ${i + 1}`,
}));
const ExampleComponent = () => {
const [selectedOptions, setSelectedOptions] = useState([]);
return (
(
)}
/>
);
};
```
## 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 or filter value — quickly from the menu.
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`.
```tsx lines expandable theme={null}
import { useEffect, useRef, useState } from "react";
import {
MultiSelectMenu,
MultiSelectMenuHandle,
MultiSelectMenuOption,
} from "@servicetitan/anvil2/beta";
import { Button, Dialog, Flex, TextField } from "@servicetitan/anvil2";
type Tag = MultiSelectMenuOption & { color: string };
function App() {
const [tags, setTags] = useState([
{ id: "bug", label: "bug", color: "#e53935" },
{ id: "feature", label: "feature", color: "#1e88e5" },
{ id: "browser", label: "browser", color: "#7b1fa2" },
{ id: "performance", label: "performance", color: "#f9a825" },
{ id: "docs", label: "docs", color: "#43a047" },
]);
const [activeFilters, setActiveFilters] = useState([]);
const menuRef = useRef(null);
const containerRef = useRef(null);
const [dialogOpen, setDialogOpen] = useState(false);
const [draftLabel, setDraftLabel] = useState("");
// Open the menu on mount so the Add-new button is visible in screenshots.
useEffect(() => {
const timer = setTimeout(() => {
const trigger = containerRef.current?.querySelector("button");
trigger?.focus();
trigger?.click();
}, 100);
return () => clearTimeout(timer);
}, []);
const openTagDialog = (initialLabel: string) => {
setDraftLabel(initialLabel.trim().toLowerCase().replace(/\s+/g, "-"));
setDialogOpen(true);
};
const saveTag = () => {
const newTag: Tag = {
id: draftLabel,
label: draftLabel,
color: "#43a047",
};
setTags((prev) => [...prev, newTag]);
setActiveFilters((prev) => [...prev, newTag]);
menuRef.current?.invalidate();
setDialogOpen(false);
};
return (
