;
}
};
**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 select field family includes two components for different use cases:
* **`SelectField`** — 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)
* **`SelectFieldSync`** — For client-side filtering of static option arrays
Both components provide a searchable dropdown interface and adaptive display modes (popover or dialog).
## SelectFieldSync (Static Options)
Use `SelectFieldSync` when you have a static list of options that can be filtered client-side.
```tsx theme={null}
import { useState } from "react";
import { SelectFieldSync } from "@servicetitan/anvil2/beta";
const options = [
{ id: 1, label: "Option One" },
{ id: 2, label: "Option Two" },
{ id: 3, label: "Option Three" },
];
const ExampleComponent = () => {
const [selectedOption, setSelectedOption] = useState(null);
return (
);
};
```
### Filtering and Sorting
By default, `SelectFieldSync` 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
/>
```
## SelectField (Async Loading)
Use `SelectField` when options need to be fetched from an API or when dealing with large datasets that require server-side filtering.
### Basic Async Loading
```tsx theme={null}
import { useState } from "react";
import { SelectField } from "@servicetitan/anvil2/beta";
const ExampleComponent = () => {
const [selectedOption, setSelectedOption] = useState(null);
return (
{
const response = await fetch(`/api/users?q=${searchValue}`);
const users = await response.json();
return users.map((user) => ({
id: user.id,
label: user.name,
}));
}}
value={selectedOption}
onSelectedOptionChange={setSelectedOption}
/>
);
};
```
### Lazy Loading Modes
`SelectField` 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, // Required for grouped options
})),
hasMore,
};
}}
// ...other props
/>
```
## 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
```
## Caching
`SelectField` 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 { SelectField } from "@servicetitan/anvil2/beta";
const ExampleComponent = () => {
const selectFieldRef = useRef(null);
const handleRefresh = () => {
selectFieldRef.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 { SelectField } from "@servicetitan/anvil2/beta";
const ExampleComponent = () => {
const selectFieldRef = useRef(null);
const handleDataSourceChange = () => {
selectFieldRef.current?.invalidate();
};
return (
);
};
```
`SelectFieldSync` 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)
// Load when user opens the dropdown
// Auto (currently equivalent to "immediate")
```
## Field States
### Error State
Display validation errors using the `error` prop:
```tsx theme={null}
```
### Hint and Description
Provide additional context with `hint` and `description`:
```tsx theme={null}
```
### Required Field
Mark a field as required with the `required` prop:
```tsx theme={null}
```
### Disabled and ReadOnly
When `disabled` is set, users cannot interact with the field.
```tsx theme={null}
// Disabled - cannot interact with the field
```
When `readOnly` is set, users can see what options exist but cannot change the current value.
```tsx theme={null}
// ReadOnly - can see options but cannot change the current value
```
### Prefix and Suffix
Add content before or after the input with `prefix` and `suffix`:
```tsx theme={null}
```
### Markdown in labels
The `label` prop supports inline markdown: bold (`**text**`), italic (`*text*`), bold and italic (`***text***`), highlight (`==text==`), and code (`` `text` ``).
```tsx lines expandable theme={null}
import { useState } from "react";
import { Flex } from "@servicetitan/anvil2";
import { SelectFieldSync, SelectFieldOption } from "@servicetitan/anvil2/beta";
const options = [
{ id: 1, label: "Option A" },
{ id: 2, label: "Option B" },
{ id: 3, label: "Option C" },
];
function App() {
const [value, setValue] = useState(null);
return (
);
}
export default App;
```
### 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.
```tsx lines expandable theme={null}
import { useState } from "react";
import { Flex } from "@servicetitan/anvil2";
import { SelectFieldSync, SelectFieldOption } from "@servicetitan/anvil2/beta";
const options = [
{ id: 1, label: "Option A" },
{ id: 2, label: "Option B" },
{ id: 3, label: "Option C" },
];
function App() {
const [value, setValue] = useState(null);
return (
);
}
export default App;
```
## 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. This is useful for AI-powered suggestions or context-aware recommendations:
```tsx theme={null}
{
const suggestions = await fetchAISuggestions(searchValue);
return suggestions.map((s) => ({ id: s.id, label: s.title }));
},
}}
loadOptions={fetchBooks}
value={selectedOption}
onSelectedOptionChange={setSelectedOption}
/>
```
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={selectedOption}
onSelectedOptionChange={setSelectedOption}
/>
```
### 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={selectedOption}
onSelectedOptionChange={setSelectedOption}
/>
```
## 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" },
];
group === "fruits" ? "Fruits" : "Vegetables"
}
value={selectedOption}
onSelectedOptionChange={setSelectedOption}
/>
```
### 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. With `groupSorter`, you can apply custom sorting (e.g., alphabetical, numerical priority).
This prop is available on `SelectFieldSync` and non-lazy `SelectField`:
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 },
];
// With SelectFieldSync
`Priority ${group}`}
groupSorter={(a, b) => Number(a) - Number(b)}
value={selectedOption}
onSelectedOptionChange={setSelectedOption}
/>
// With async SelectField (non-lazy)
options}
groupToString={(group) => `Priority ${group}`}
groupSorter={(a, b) => Number(a) - Number(b)}
value={selectedOption}
onSelectedOptionChange={setSelectedOption}
/>
```
### Mixed Grouped and Ungrouped Options
Options without a `group` property appear after all grouped sections:
```tsx theme={null}
const options = [
{ id: 1, label: "Apple", group: "fruits" },
{ id: 2, label: "Banana", group: "fruits" },
{ id: 3, label: "Other Item" }, // No group - appears last
{ id: 4, label: "Carrot", group: "vegetables" },
];
```
## 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, and keyboard navigation.
```tsx theme={null}
import { useState } from "react";
import { SelectFieldSync } from "@servicetitan/anvil2/beta";
const options = Array.from({ length: 5000 }, (_, i) => ({
id: i,
label: `Option ${i + 1}`,
}));
const ExampleComponent = () => {
const [selectedOption, setSelectedOption] = useState(null);
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 customer, tag, or category — 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`.
```tsx lines expandable theme={null}
import { useEffect, useRef, useState } from "react";
import {
SelectField,
SelectFieldHandle,
SelectFieldOption,
} from "@servicetitan/anvil2/beta";
import { Button, Dialog, Flex, TextField } from "@servicetitan/anvil2";
type Customer = SelectFieldOption & { phone: string };
function App() {
const [customers, setCustomers] = useState([
{ id: "1", label: "Acme HVAC", phone: "(555) 123-4567" },
{ id: "2", label: "Bluebird Plumbing", phone: "(555) 234-5678" },
{ id: "3", label: "Carolina Electric", phone: "(555) 345-6789" },
]);
const [selected, setSelected] = useState(null);
const selectRef = useRef(null);
const containerRef = useRef(null);
const [dialogOpen, setDialogOpen] = useState(false);
const [draftName, setDraftName] = useState("");
const [draftPhone, setDraftPhone] = useState("");
// Open the menu on mount so the Add-new button is visible in screenshots.
useEffect(() => {
const timer = setTimeout(() => {
const trigger = containerRef.current?.querySelector("input");
trigger?.focus();
trigger?.click();
}, 100);
return () => clearTimeout(timer);
}, []);
const openCustomerDialog = (initialName: string) => {
setDraftName(initialName);
setDraftPhone("");
setDialogOpen(true);
};
const saveCustomer = () => {
const newCustomer: Customer = {
id: crypto.randomUUID(),
label: draftName,
phone: draftPhone,
};
setCustomers((prev) => [...prev, newCustomer]);
setSelected(newCustomer);
selectRef.current?.invalidate();
setDialogOpen(false);
};
return (
