);
}
export default App;
```
## Common Examples
```tsx theme={null}
import { useState } from "react";
import { Combobox } from "@servicetitan/anvil2";
const items = [
{ id: 1, name: "First item" },
// ...more items...
];
const ExampleComponent = () => {
const [selectedItem, setSelectedItem] = useState();
return (
item ? item.name : ""}
itemToKey={(item) => item ? item.id : null}
selectedItem={selectedItem}
onChange={setSelectedItem}
filterOptions={{ keys: ["name"] }}
>
{({ items }) => (
{items.map((item, i) => (
{item.name}
))}
)}
);
```
### Combobox components
The Anvil2 combobox is made up of a `Combobox` component and a few sub-components that can be used together to build simple or complex select drop-downs.
* `Combobox`: the parent component to configure comboboxes.
* `Combobox.SearchField`: used to create a searchable select input to use with a combobox list in a drop-down.
* `Combobox.Content`: popover that passes an `items` array to its `children` to construct combobox items.
* `Combobox.List`: organizes combobox items in the drop-down list.
* `Combobox.Item`: used to construct the items within the combobox drop-down.
* `Combobox.Empty`: optionally used to customize empty results message.
### Multi-selects
To allow the user to select multiple items, set the `multiple` prop of the `Combobox` to `true`. In addition, props such as `selectedItem` will be replaced with `selectedItems` (note the "s" at the end) and will expect an array.
```tsx lines expandable theme={null}
import { Combobox } from "@servicetitan/anvil2";
import { useState } from "react";
type Item = {
id: number;
name: string;
};
const items = [
{ id: 1, name: "First item" },
{ id: 2, name: "Second item" },
{ id: 3, name: "Third item" },
{ id: 4, name: "Fourth item" },
{ id: 5, name: "Fifth item" },
{ id: 6, name: "Sixth item" },
{ id: 7, name: "Seventh item" },
{ id: 8, name: "Eighth item" },
{ id: 9, name: "Ninth item" },
{ id: 10, name: "Tenth item" },
];
function App() {
const [selectedItems, setSelectedItems] = useState([]);
return (
);
}
export default App;
```
### Select all for multi-selects
To add a "Select All" option at the top of a multi-select combobox dropdown, use the `selectAll` prop. This prop accepts an object with `label`, `onSelection`, and `isChecked` properties. The `onSelection` callback is called when the user clicks the Select All option, and `isChecked` controls whether the checkbox appears checked.
Note: The "Select All" option does not automatically select all items when the combobox is opened. It is up to the developer to handle the selection of all items when the "Select All" option is clicked. This means it is incompatible with using `Combobox` in an uncontrolled way.
```tsx lines expandable theme={null}
import { Combobox } from "@servicetitan/anvil2";
import { useState } from "react";
type Item = {
id: number;
name: string;
};
const items: Item[] = [
{ id: 1, name: "Apple" },
{ id: 2, name: "Banana" },
{ id: 3, name: "Blueberry" },
{ id: 4, name: "Grapefruit" },
{ id: 5, name: "Orange" },
{ id: 6, name: "Peach" },
{ id: 7, name: "Pomegranate" },
{ id: 8, name: "Raspberry" },
{ id: 9, name: "Strawberry" },
{ id: 10, name: "Watermelon" },
];
function App() {
const [selectedItems, setSelected] = useState();
return (
);
}
export default App;
```
#### Notes for building selects
* The `itemToString` prop passes an `item` object and expects a `string` return type. This is used to format the text of each combobox item within the search field input (after selecting an item) based on the provided `item` object type.
* The `itemToKey` prop passes an `item` object and expects something that can be used to identify the item, such as an `id`. This is used for identity comparisons, so if this prop is omitted, the `item`s will be compared by reference equality instead.
* The `filterOptions` prop is used to filter the items using the [match-sorter](https://github.com/kentcdodds/match-sorter?tab=readme-ov-file) library. See [their docs](https://github.com/kentcdodds/match-sorter?tab=readme-ov-file#advanced-options) for more info on the options that can be provided.
* The `selectedItem`/`selectedItems` props allow the `Combobox` to be used as a controlled component.
* For easily managing the selected item state, the `onChange` prop accepts a `setState` function, which is the second item in the array that a `useState` function returns:
```tsx theme={null}
const ExampleComponent = () => {
const [selected, setSelected] = useState();
return
}
```
#### Compare using `itemToKey` or reference equality
The `itemToKey` prop is used to compare `items` using a unique identifier. By default, the `Combobox` component does searches and comparisons using reference equality. That means that the `Combobox` may not behave how you expect if your code is generating new references for your `items` on every render:
```tsx theme={null}
const items = [
{ id: 1, name: "First item" },
{ id: 2, name: "Second item" },
{ id: 3, name: "Third item" },
{ id: 4, name: "Fourth item" },
{ id: 5, name: "Fifth item" },
];
const ExampleComponent = () => {
const [selected, setSelected] = useState();
// WARNING! This will create a new reference for every item on every render!
const newItems = items.map(item => { ...item, someChange: Math.random() });
return (
{...}
)
}
```
Some ways have stable references might be to perform the reference modifications outside of React's render cycle or to use `React.useMemo` to memoize computations on `items` and only update the references when something has meaningfully changed.
However, in cases like this, it's probably more likely you'd prefer to have your `items` compared by a specific key in your object rather than by reference equality. And so you can do that by passing in an `itemToKey` function that takes an item and returns a unique key:
```tsx theme={null}
const items = [
{ id: 1, name: "First item" },
{ id: 2, name: "Second item" },
{ id: 3, name: "Third item" },
{ id: 4, name: "Fourth item" },
{ id: 5, name: "Fifth item" },
];
const ExampleComponent = () => {
const [selected, setSelected] = useState();
const newItems = items.map(item => { ...item, someChange: Math.random() });
return (
item?.id}
>
{...}
)
}
```
#### Passing filtered items through the combobox components
The `items` array passed to the `Combobox` is automatically filtered based on the user typing in the search input and the `keys` in the `filterOption` prop. After filtering, it is passed through the `Combobox.Content` as a parameter used to generate the `children`.
```tsx theme={null}
// objects in items array can have any type
const items = [
{ id: 1, label: "First item", alias: "one" },
{ id: 2, label: "Second item", alias: "two" },
{ id: 3, label: "Third item", alias: "three" },
];
const ExampleComponent = () => {
const [selectedItems, setSelectedItems] = useState([]);
return (
item?.label ?? ""}
itemToKey={(item) => item?.id ?? null}
selectedItems={selectedItems}
onChange={setSelectedItems}
/* strings in keys array should match the
searchable fields in items objects */
filterOptions={{ keys: ["label", "alias"] }}
>
{/* matches items array, with filtering */}
{({ items }) => (
{items.map((item, index) => (
{item.label}
))}
)}
);
};
```
### Adding a new item when there is no exact match
To allow the user to add a new item when their search returns no exact matches, use the `Combobox.ItemAddNew` component. This component provides an `onSelection` callback, and that callback will need to be used to update both your list of items and your selected item.
Your `onSelection` callback will need to both update the list of items and update the `selectedItem`/`selectedItems`, so we recommend that you use a controlled `Combobox` when you need the ability to add a new item:
```tsx lines expandable theme={null}
import { Combobox, Text } from "@servicetitan/anvil2";
import { useState } from "react";
type Item = {
id: number;
name: string;
};
function App() {
const [items, setItems] = useState([
{ id: 1, name: "First item" },
{ id: 2, name: "Second item" },
{ id: 3, name: "Third item" },
{ id: 4, name: "Fourth item" },
{ id: 5, name: "Fifth item" },
{ id: 6, name: "Sixth item" },
{ id: 7, name: "Seventh item" },
{ id: 8, name: "Eighth item" },
{ id: 9, name: "Ninth item" },
{ id: 10, name: "Tenth item" },
]);
const [selectedItems, setSelectedItems] = useState([]);
const handleAddNew = (inputValue: string) => {
const newItem = { id: items.length + 1, name: inputValue };
setItems((prevItems) => [...prevItems, newItem]);
setSelectedItems((prevItems) =>
prevItems != null ? [...prevItems, newItem] : [newItem],
);
};
return (
);
}
export default App;
```
### Disabling combobox popovers
Comboboxes can be used to create searchable select lists without a drop-down. If `disablePopover` is set to `true` on the `Combobox.Content`, the list will always render. This is especially useful if the combobox exists within a custom [popover](/docs/web/components/popover/design).
```tsx lines expandable theme={null}
import { Combobox, Popover } from "@servicetitan/anvil2";
import { useState } from "react";
type Item = {
id: string;
name: string;
};
const technicians = [
{ id: "cs-0", name: "Cory Sparks" },
{ id: "jb-1", name: "Jessica Brees" },
{ id: "jc-2", name: "Johnny Carpenter" },
{ id: "rp-3", name: "Rusty Pipes" },
{ id: "sp-4", name: "Silvia Plomería" },
];
function App() {
const [selectedItems, setSelectedItems] = useState([]);
return (
);
}
export default App;
```
### Combobox virtualization example
`Combobox.Content` renders a function that passes down the list of filtered items as children, allowing the `Combobox.List` component to be used with virtualization libraries, which often require an additional wrapper component around the items being virtualized. The following example uses `react-window`'s `FixedSizeList` component for virtualizing the list of items:
```tsx theme={null}
import { useState } from "react";
import { Combobox } from "@servicetitan/anvil2";
import { FixedSizeList as List } from "react-window";
const items = [
{ id: 1, name: "First item" },
// ...more items...
];
const ExampleComponent = () => {
const [selectedItem, setSelectedItem] = useState();
return (
(item ? item.name : "")}
itemToKey={(item) => (item ? item.id : null)}
onChange={setSelectedItem}
filterOptions={{ keys: ["name"] }}
>
{({ items }) => (
{({ index, style }) => (
{items[index].name}
)}
)}
);
};
```
```tsx theme={null}
item?.name ?? ""}
itemToKey={(item) => item?.id ?? null}
multiple={false}
onChange={setSelectedItem}
filterOptions={{ keys: ["name"] }}
/>
```
## `Combobox` and `Combobox.Select` Props
In addition to the props listed below, the `Combobox` and `Combobox.Select` components can accept any valid HTML `div` props.
* The default `Combobox` also accepts the props listed in the [downshift UseComboboxProps type](https://github.com/downshift-js/downshift/blob/v8.5.0/typings/index.d.ts#L537).
* The `Combobox.Select` component alternatively extends the [downshift UseSelectProps type](https://github.com/downshift-js/downshift/blob/v8.5.0/typings/index.d.ts#L340). Note: Props related to the input are not included for Combobox.Select, since there is no search field. (`defaultInputValue, inputId`, etc.)
The default selected item for single-select combobox.
The default selected item(s) for multi-select combobox.
Disables the combobox, preventing user interaction.
Prevent input from clearing when item is selected. **Note:** Only works with
`Combobox` with `multiple={true}`
Remove the clear button to disable user clearing the input after selecting.
**Note:** Only works with `Combobox.Select` with `multiple` is not `true`
Prevent the drop-down popover from closing when the user clicks outside of it.
Prevent the drop-down from closing when item is selected. **Note:** Only works
with `Combobox` with `multiple={true}`
See the [match-sorter MatchSorterOptions
type](https://github.com/kentcdodds/match-sorter/blob/v6.3.4/src/index.ts#L50)
**Note:** Not available on `Combobox.Select`
Name of the property on each item to group by. When provided, items are organized into labeled sections in the dropdown based on the value of this property.
Function to compare two group values for sorting. Must return a negative number if `a` should appear before `b`, and a positive number if `b` should appear before `a`. `ComboboxGroupByValue` is `string | number`.
Function to convert group values to display labels. When not provided, the raw group key value is used as the label. `ComboboxGroupByValue` is `string | number`.
Callback when selection changes. For single-select, receives the selected item or null. For multi-select, receives an array of selected items.
Makes the combobox read-only, allowing focus but preventing changes.
Configuration for "Select All" option in multi-select comboboxes. When provided, adds a "Select All"
option at the top of the dropdown list. Only available when `multiple={true}`.
```tsx theme={null}
```
## `Combobox.SearchField` and `Combobox.SelectTrigger` Props
Control opening the `moreInfo` tooltip.
Prefix content displayed before the input.
This function passes the selected item as a parameter and returns an object to
merge into the selected item `Chip` props.
```tsx theme={null}
{({ items }) => (
{items.map((item, index) => (
{item.name}
))}
)}
```
## `Combobox.Content` Props
```tsx theme={null}
{items.map((item, index) => (
{item.name}
))}
```
## `Combobox.List` Props
```tsx theme={null}
Item content
```
## `Combobox.Item` Props
```tsx theme={null}
console.log(inputValue)}>
Add new item
```
## `Combobox.ItemAddNew` Props
```tsx theme={null}
No results found
```
## `Combobox.Empty` Props
