> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Filter Bar – Design
> Standalone filter bar component for filtering content
export const LiveCode = ({children, customHeight, clickToLoad, example, fullWidth, fullHeight, hideCodeInLiveCode, screenshot, screenshotOnly, showCode: showCodeProp}) => {
const SCREENSHOTS_BASE = "https://servicetitan.github.io/anvil2-docs-live-code/screenshots";
const STACKBLITZ_BASE = "https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples";
const [showCodeBlock, setShowCodeBlock] = useState(showCodeProp ?? false);
const [isLocalOverride, setIsLocalOverride] = useState(false);
useEffect(() => {
const examplePath = `/images/live-code-screenshots-tmp/${example}.png`;
fetch(examplePath, {
method: "HEAD"
}).then(r => {
if (r.ok) setIsLocalOverride(true);
}).catch(() => {});
}, [example]);
const screenshotBase = isLocalOverride ? "/images/live-code-screenshots-tmp" : SCREENSHOTS_BASE;
if (screenshotOnly) {
return
{!showCodeProp ?
setShowCodeBlock(!showCodeBlock)} style={{
appearance: "none"
}}>
{showCodeBlock ? "Hide code" : "Show code"}
: null}
StackBlitz demo
;
}
};
export const DoDont = ({text, type, children}) => {
return <>
{type === "do" &&
{children &&
{children}
}
Do
{text && {text} }
{children &&
{children}
}
Don't
{text && {text} }
{children &&
{children}
}
Caution
{text && {text} }
{single}
{single}
: single;
};
## Live Demo
```tsx lines theme={null}
import {
FilterBar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
type SelectItem = { id: string; label: string };
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const multiSelectCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([
// Boolean filter
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean",
checked: true,
},
// Single select filter
{
id: "categoryFilter",
type: "singleSelect",
label: "Single select",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
// Multi select filter
{
id: "categoryMultiSelectFilter",
type: "multiSelect",
label: "Multi select",
items: multiSelectCategoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
// Date filter
{
id: "dateFilter",
type: "date",
label: "Single date",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
// Date range filter
{
id: "dateRangeFilter",
type: "dateRange",
label: "Multi date",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
// Custom filter
{
...customFilter,
value: { id: 2, label: "Option 2" },
},
]);
// Update label based on current filter value for custom filter
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom filter: ${currentValue.label}`
: "Custom filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
return (
);
}
export default App;
```
## Anatomy
The **Filter Bar** consists of several elements that work together to provide filtering capabilities.
1. **Filter Button** - Interactive button that opens a popover or drawer containing filter options
2. **Selected Filter** - Visual indicator showing when a filter has an active selection
3. **Selected Item (for multi select)** - Displays the count of selected items in a multi-select filter, using a chip
4. **Label** - Text identifier that describes what the filter controls
5. **Selected Item (for single select)** - Displays the currently selected option for single-select filters
6. **All Filters** - Button that opens the filter drawer for batch editing of all filters. Appears whenever at least one filter is unreachable from the toolbar.
7. **Search Field (Optional)** - Input field for filtering available options within single-select and multi-select filters
8. **Popover of filter items** - Dropdown panel that appears when a filter button is clicked, containing the filter's selection interface
9. **Apply and cancel filter (Optional)** - Action buttons that appear at the bottom of filter popovers when controlled filtering is enabled
## Options
The **Filter Bar** supports the following configurations to accommodate various filtering scenarios and user interaction patterns.
### Types of Filters
#### Boolean
```tsx lines theme={null}
import { Toolbar } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [filters, setFilters] = useState([
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean Filter",
checked: false,
},
{
type: "boolean",
id: "booleanFilterId2",
label: "Boolean Filter 2",
checked: true,
},
]);
return (
{filters.map((filter) => (
{
setFilters((prev) =>
prev.map((f) =>
f.id === filter.id ? { ...f, checked: !f.checked } : f,
),
);
console.log("Filter toggled:", filter.id);
}}
>
{filter.label}
))}
);
}
export default App;
```
Boolean filters provide a simple toggle mechanism for on/off states. Users click the filter button to activate or deactivate the filter, with the button's visual state indicating the current selection.
##### Content Guidelines
* The boolean label stays the same across states. Think of this like the label of a Checkbox, which does not change when it is checked or unchecked.
#### Single Select
```tsx lines theme={null}
import { Flex } from "@servicetitan/anvil2";
import { FilterBar, type Filter } from "@servicetitan/anvil2/beta";
import { useState, useEffect } from "react";
type SelectItem = { id: string; label: string };
function App() {
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const statusOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const [filters, setFilters] = useState([
{
id: "categoryFilter",
type: "singleSelect",
label: "Label",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
{
id: "statusFilter",
type: "singleSelect",
label: "Label",
items: statusOptions,
},
]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="categoryFilter"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
Single select filters display a dropdown list of options where users can choose one item. The selected option appears in the filter button label, and clicking the button opens a popover with the full list of available options.
##### Content Guidelines
* Single selection contains a label, followed by a : , a space, then the selected item. A Chip does not appear in any single selection scenario.
* Example "Group by", "Group by: Job"
#### Multi Select
```tsx lines theme={null}
import { Flex } from "@servicetitan/anvil2";
import { FilterBar, type Filter } from "@servicetitan/anvil2/beta";
import { useState, useEffect } from "react";
type SelectItem = { id: string; label: string };
function App() {
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
const statusOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
const [filters, setFilters] = useState([
{
id: "categoryFilter",
type: "multiSelect",
label: "Label",
items: categoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
{
id: "statusFilter",
type: "multiSelect",
label: "Label",
items: statusOptions,
selectedItems: [],
},
]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="categoryFilter"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
Multi select filters allow users to select multiple options from a list. The filter button displays a chip with the count of selected items when selections are active. Clicking the button opens a popover where users can select or deselect multiple options.
##### Content Guidelines
* Multi selection contains a label, followed by a Chip. Multi selection never shows the selected items in the Toolbar itself.
* Example "Group by", "Group by (1)", "Group by (2)"
#### Date
```tsx lines theme={null}
import { Flex } from "@servicetitan/anvil2";
import { FilterBar, type Filter } from "@servicetitan/anvil2/beta";
import { useState, useEffect } from "react";
function App() {
const [filters, setFilters] = useState([
{
id: "categoryFilter",
type: "date",
label: "Label",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
{
id: "statusFilter",
type: "date",
label: "Label",
mode: "mm/dd/yyyy",
},
]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="categoryFilter"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
Date filters provide a calendar interface for selecting a single date. The filter button displays the selected date in the configured format, and clicking it opens a popover with a calendar picker.
##### Date Range
```tsx lines theme={null}
import { Flex } from "@servicetitan/anvil2";
import { FilterBar, type Filter } from "@servicetitan/anvil2/beta";
import { useState, useEffect } from "react";
function App() {
const [filters, setFilters] = useState([
{
id: "categoryFilter",
type: "dateRange",
label: "Label",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
{
id: "statusFilter",
type: "dateRange",
label: "Label",
mode: "mm/dd/yyyy",
},
]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="categoryFilter"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
Date range filters enable users to select a start date and an end date. The filter button displays both dates when selected, and clicking it opens a popover with dual calendar pickers for selecting the range.
##### Date List
```tsx lines theme={null}
import { Flex } from "@servicetitan/anvil2";
import {
FilterBar,
type Filter,
type DateListOption,
} from "@servicetitan/anvil2/beta";
import { DateTime } from "luxon";
import { useState, useEffect } from "react";
function App() {
const today = DateTime.local().startOf("day");
const dateListOptions: DateListOption[] = [
{ id: "today", label: "Today", value: today.toISODate() },
{
id: "yesterday",
label: "Yesterday",
value: today.minus({ days: 1 }).toISODate(),
},
{
id: "last7Days",
label: "Last 7 days",
value: {
startDate: today.minus({ days: 6 }).toISODate() ?? "",
endDate: today.toISODate() ?? "",
},
},
];
const [filters, setFilters] = useState([
{
id: "dueDateFilter",
type: "dateList",
label: "Due date",
mode: "mm/dd/yyyy",
options: dateListOptions,
},
]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="dueDateFilter"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
A Date List filter renders a single-select list of date "buckets" (e.g.
"Today", "Last 7 days") followed by four menu options (`On…`, `Before…`,
`After…`, `Custom Range…`). Consumer-supplied options resolve to a date or
range and commit immediately on click; menu options open a Dialog with the
appropriate date picker. The popover never shows Apply/Cancel since picking
an option is itself the confirming action.
##### Content Guidelines
* The Calendar icon and label are always present.
* For the label, use "Date" if there is no specific name that would be more descriptive.
* Single selection examples:
* "Date", "Date: Jan 3, 2025"
* "Last Modifed On", "Last Modified On: Nov 1, 2026"
* Date range examples:
* "Date", "Date: Jan 3 – Jan 10, 2025"
* "Date", "Date: Dec 31, 2025 – Jan 1, 2026"
* Date list examples:
* "Due date" (no selection)
* "Today: Jan 28, 2026" (consumer single-date option)
* "Last 7 days: Jan 28 – Feb 4, 2026" (consumer range option)
* "On: Sept 12, 2026" (menu `On…`, `Before…`, `After…` after dialog)
* "Jan 28 – Feb 4, 2026" (menu `Custom Range…` after dialog — no label prefix since the range is self-explanatory)
###### Date Format guidelines
* Month as 3 letter abbreviation
* Date without a leading zero
* Comma separation
* Full numeric year, omitted if a date range for the first value and both dates are in the same year.
* An en dash (–) between dates
###### Why does the format not use MM/DD/YYYY?
Accessibility standards require explanation of the format on the page when using ambiguous formats like 01/05/2026. Filter Button avoids this requirement by spelling out the month part. Users do not type directly into Filter Button, so the format remains clear and accessible.
###### Why does the format not spell out the whole month?
Filter Bar prioritizes horizontal space efficiency over verbosity. In context, the date icon further emphasizes a user is reading a month.
#### Custom
```tsx lines theme={null}
import {
FilterBar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom Filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([customFilter]);
// Update label based on current filter value
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom Filter: ${currentValue.label}`
: "Custom Filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="customFilterId"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
{
setFilters(updatedFilters);
}}
flexGrow={1}
/>
);
}
export default App;
```
Custom filters provide complete flexibility for implementing specialized filtering interfaces. Developers define custom render functions for both the popover and drawer views, allowing any type of filter control to be integrated into the toolbar.
##### Content Guidelines
* Custom filters must use a label. It may either use selection text or a Chip, depending on the intent of the custom filter.
### Apply and Cancel
```tsx lines theme={null}
import { Flex } from "@servicetitan/anvil2";
import { FilterBar, type Filter } from "@servicetitan/anvil2/beta";
import { useState, useEffect } from "react";
type SelectItem = { id: string; label: string };
function App() {
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const [filters, setFilters] = useState([
{
id: "categoryFilter",
type: "singleSelect",
label: "Label",
items: categoryOptions,
},
]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="categoryFilter"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
By default, filter selections apply immediately when a user makes a choice. When controlled filtering is enabled, Apply and Cancel buttons appear at the bottom of filter popovers. Users can make multiple changes in draft state, then click Apply to submit all changes at once or Cancel to discard them. The filter drawer always operates in controlled mode with Apply and Cancel buttons in the footer. See [Filter Fetching](#filter-fetching) for more information on when to use Apply and Cancel.
### Search
```tsx lines theme={null}
import { Flex } from "@servicetitan/anvil2";
import { FilterBar, type Filter } from "@servicetitan/anvil2/beta";
import { useState, useEffect } from "react";
type SelectItem = { id: string; label: string };
function App() {
const allCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
const [categoryOptions, setCategoryOptions] =
useState(allCategoryOptions);
const [filters, setFilters] = useState([
{
id: "categoryFilter",
type: "singleSelect",
label: "Label",
items: categoryOptions,
hasSearch: true,
onSearch: (searchTerm: string) => {
if (!searchTerm) {
setCategoryOptions(allCategoryOptions);
} else {
const filtered = allCategoryOptions.filter((option) =>
option.label.toLowerCase().includes(searchTerm.toLowerCase()),
);
setCategoryOptions(filtered);
}
},
onSearchClear: () => {
setCategoryOptions(allCategoryOptions);
},
},
]);
// Update filters when categoryOptions change
useEffect(() => {
setFilters((prev) =>
prev.map((filter) =>
filter.id === "categoryFilter"
? { ...filter, items: categoryOptions }
: filter,
),
);
}, [categoryOptions]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-id="categoryFilter"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
Single select and multi select filters can include an optional search field at the top of their popovers. The search field allows users to filter the available options by typing, making it easier to find specific items in large lists. The implementing team controls how the search filters the items through callback functions.
## Behavior
The **Filter Bar** responds to user interaction and space constraints with distinct behaviors for filter management and layout adaptation.
### All Filters
```tsx lines theme={null}
import {
FilterBar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
type SelectItem = { id: string; label: string };
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const multiSelectCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([
// Boolean filter
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean",
checked: true,
},
// Single select filter
{
id: "categoryFilter",
type: "singleSelect",
label: "Single select",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
// Multi select filter
{
id: "categoryMultiSelectFilter",
type: "multiSelect",
label: "Multi select",
items: multiSelectCategoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
// Date filter
{
id: "dateFilter",
type: "date",
label: "Single date",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
// Date range filter
{
id: "dateRangeFilter",
type: "dateRange",
label: "Multi date",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
// Custom filter
{
...customFilter,
value: { id: 2, label: "Option 2" },
},
]);
// Update label based on current filter value for custom filter
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom filter: ${currentValue.label}`
: "Custom filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-anv="filter-group-drawer-trigger"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
The **Filter Bar** surfaces an "All Filters" button that opens the filter drawer for managing multiple filters at once. The button only appears when at least one filter is unreachable from the toolbar — that is, when a filter is configured as drawer-only, when an inline filter has overflowed, or when the container is too narrow to show inline filters at all. When every filter fits inline and none are drawer-only, the button does not render. While present, the button shows a chip with the count of active filters that need the drawer to access.
### Drawer of Filters
The filter drawer is a side panel that displays all available filters in a unified interface. It maintains draft state for all filters until the user clicks Apply, enabling batch updates. The drawer includes a Clear All button that resets all filters to their default states. This batch filtering approach allows users to make multiple filter changes before committing them.
### Drawer-only Filters
Setting `drawerOnly: true` on a filter keeps it accessible only through the filter drawer; it never renders inline in the toolbar, even when there is room for it. Use this to surface lower-priority filters or filters whose UI does not fit the toolbar shape without crowding the primary filters. The flag applies to every filter type — boolean, single select, multi select, date, date range, date list, and custom.
A drawer-only custom filter only requires `drawerRender` — `buttonRender` is forbidden, since the filter never appears inline.
### Overflow
#### Wrapping
```tsx lines theme={null}
import {
FilterBar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
type SelectItem = { id: string; label: string };
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const multiSelectCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([
// Boolean filter
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean",
checked: true,
},
// Single select filter
{
id: "categoryFilter",
type: "singleSelect",
label: "Single select",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
// Multi select filter
{
id: "categoryMultiSelectFilter",
type: "multiSelect",
label: "Multi select",
items: multiSelectCategoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
// Date filter
{
id: "dateFilter",
type: "date",
label: "Single date",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
// Date range filter
{
id: "dateRangeFilter",
type: "dateRange",
label: "Multi date",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
// Custom filter
{
...customFilter,
value: { id: 2, label: "Option 2" },
},
]);
// Update label based on current filter value for custom filter
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom filter: ${currentValue.label}`
: "Custom filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
return (
);
}
export default App;
```
In wrap mode, filters that don't fit on a single line automatically wrap to the next line. This ensures all filters remain visible while adapting to the available horizontal space. Wrap mode is the default overflow behavior.
#### Collapsed
```tsx lines theme={null}
import {
FilterBar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
type SelectItem = { id: string; label: string };
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const multiSelectCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([
// Boolean filter
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean",
checked: true,
},
// Single select filter
{
id: "categoryFilter",
type: "singleSelect",
label: "Single select",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
// Multi select filter
{
id: "categoryMultiSelectFilter",
type: "multiSelect",
label: "Multi select",
items: multiSelectCategoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
// Date filter
{
id: "dateFilter",
type: "date",
label: "Single date",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
// Date range filter
{
id: "dateRangeFilter",
type: "dateRange",
label: "Multi date",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
// Custom filter
{
...customFilter,
value: { id: 2, label: "Option 2" },
},
]);
// Update label based on current filter value for custom filter
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom filter: ${currentValue.label}`
: "Custom filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
return (
);
}
export default App;
```
In collapse mode, filters that don't fit within the available space are removed from view. Unlike other toolbar items that move to an overflow menu, hidden filters are simply not displayed. All filters remain accessible through the filter drawer regardless of overflow mode. The filters group takes priority over other toolbar groups, meaning filters wrap or collapse before secondary toolbar actions.
### Responsive Behavior
At smaller breakpoints (xs and sm), inline filters automatically hide and only the "All Filters" drawer trigger button remains visible. This responsive behavior uses container queries to detect available space and adapts the interface to ensure usability on mobile devices. The drawer provides full access to all filters regardless of screen size.
## Keyboard Interaction
Users can navigate the **Filter Bar** using standard keyboard controls.
| Key | Description |
| ---------- | ------------------------------------------------------------------------ |
| Tab | Moves focus between filter buttons and the "All Filters" button |
| Enter | Opens the focused filter's popover or activates a boolean filter toggle |
| Escape | Closes an open Popover or Drawer and returns focus to the trigger button |
| Arrow Keys | Navigate through options within filter Popovers and Drawers |
| Space | Activates focused filter controls within popovers and drawers |
## When to use
Use the Filter Bar when needing to apply the filter pattern to content.
## How to use
### Where and how filters are represented
The All Filter acts as a central hub for all the available filters for end users. It always opens into a Drawer. It's always labeled as 'Filters'.
### Grouping Filters
On the page, filters exists as part of a larger Toolbar
* In general, show most-used filters first.
* Rarely used filters do not have to be shown on the page and may be placed within the Drawer layout instead.
* If a filter group is used consistently within a product area, consider consistency in ordering across the area.
* Avoid changing the placement or conditions of actions such as the 'Clear All', 'Filters', and search bar.
* Multiple filter groups may exist if a page contains multiple layers of filterable content and each section needs its own unique filtering.
### Filter Fetching
Filter fetching refers to when filters get applied to an area. There are three types of filter fetching: instant, apply per-filter, and batch.
#### Instant filter
Instant filtering begins the process of filtering results the moment a user makes a selection within a filter. This can only occur in the Toolbar filter view and not in the Drawer. This is the generally preferred option for filtering as it reduces the amount of steps users must take.
```tsx lines theme={null}
import {
FilterBar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
type SelectItem = { id: string; label: string };
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const multiSelectCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([
// Boolean filter
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean",
checked: true,
},
// Single select filter
{
id: "categoryFilter",
type: "singleSelect",
label: "Single select",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
// Multi select filter
{
id: "categoryMultiSelectFilter",
type: "multiSelect",
label: "Multi select",
items: multiSelectCategoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
// Date filter
{
id: "dateFilter",
type: "date",
label: "Single date",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
// Date range filter
{
id: "dateRangeFilter",
type: "dateRange",
label: "Multi date",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
// Custom filter
{
...customFilter,
value: { id: 2, label: "Option 2" },
},
]);
// Update label based on current filter value for custom filter
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom filter: ${currentValue.label}`
: "Custom filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
return (
);
}
export default App;
```
#### Apply per-filter
Apply per-filter sets individual Apply + Cancel actions onto each individual filter. This is a useful method when performance is particularly important.
```tsx lines theme={null}
import {
FilterBar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
type SelectItem = { id: string; label: string };
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const multiSelectCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([
// Boolean filter
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean",
checked: true,
},
// Single select filter
{
id: "categoryFilter",
type: "singleSelect",
label: "Single select",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
// Multi select filter
{
id: "categoryMultiSelectFilter",
type: "multiSelect",
label: "Multi select",
items: multiSelectCategoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
// Date filter
{
id: "dateFilter",
type: "date",
label: "Single date",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
// Date range filter
{
id: "dateRangeFilter",
type: "dateRange",
label: "Multi date",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
// Custom filter
{
...customFilter,
value: { id: 2, label: "Option 2" },
},
]);
// Update label based on current filter value for custom filter
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom filter: ${currentValue.label}`
: "Custom filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
return (
);
}
export default App;
```
#### Batch filter
Batch filtering waits to apply a filter only after clicking a standalone Apply action. Batch filtering is not made available in the standard Toolbar view, while being the only method used in the Drawer view.
```tsx lines theme={null}
import {
Toolbar,
type Filter,
type CustomFilter,
} from "@servicetitan/anvil2/beta";
import { Radio, Combobox, Flex } from "@servicetitan/anvil2";
import { useState, useEffect } from "react";
type ComboboxItem = {
id: string;
label: string;
};
const comboboxItems: ComboboxItem[] = [
{ id: "is", label: "Is" },
{ id: "isNot", label: "Is Not" },
];
type CustomFilterValue = {
id: number;
label: string;
};
const filterOptions = [
{ id: 1, label: "Option 1" },
{ id: 2, label: "Option 2" },
{ id: 3, label: "Option 3" },
];
type SelectItem = { id: string; label: string };
const categoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
];
const multiSelectCategoryOptions: SelectItem[] = [
{ id: "option1", label: "Option 1" },
{ id: "option2", label: "Option 2" },
{ id: "option3", label: "Option 3" },
{ id: "option4", label: "Option 4" },
{ id: "option5", label: "Option 5" },
];
function OperatorCombobox() {
const [selectedItem, setSelectedItem] = useState(
comboboxItems[0],
);
return (
(item ? item.label : "")}
itemToKey={(item) => (item ? item.id : null)}
selectedItem={selectedItem}
onChange={setSelectedItem}
>
{({ items }) => (
{items.map((item, i) => (
{item.label}
))}
)}
);
}
function App() {
const customFilter: CustomFilter = {
id: "customFilterId",
type: "custom",
label: "Custom filter",
buttonRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
drawerRender: ({ value, onChange }) => (
{filterOptions.map((option) => (
{
if (!e?.target) return;
const selected = filterOptions.find(
(opt) => opt.id.toString() === e.target.value,
);
onChange(selected);
}}
/>
))}
),
};
const [filters, setFilters] = useState([
// Boolean filter
{
type: "boolean",
id: "booleanFilterId",
label: "Boolean",
checked: true,
},
// Single select filter
{
id: "categoryFilter",
type: "singleSelect",
label: "Single select",
items: categoryOptions,
selectedItem: { id: "option2", label: "Option 2" },
},
// Multi select filter
{
id: "categoryMultiSelectFilter",
type: "multiSelect",
label: "Multi select",
items: multiSelectCategoryOptions,
selectedItems: [
{ id: "option2", label: "Option 2" },
{ id: "option4", label: "Option 4" },
],
},
// Date filter
{
id: "dateFilter",
type: "date",
label: "Single date",
mode: "mm/dd/yyyy",
value: "2026-01-01",
},
// Date range filter
{
id: "dateRangeFilter",
type: "dateRange",
label: "Multi date",
mode: "mm/dd/yyyy",
value: {
startDate: "2026-01-01",
endDate: "2026-01-14",
},
},
// Custom filter
{
...customFilter,
value: { id: 2, label: "Option 2" },
},
]);
// Update label based on current filter value for custom filter
useEffect(() => {
const currentFilter = filters.find((f) => f.id === "customFilterId") as
| CustomFilter
| undefined;
if (currentFilter) {
const currentValue = currentFilter.value;
const newLabel = currentValue
? `Custom filter: ${currentValue.label}`
: "Custom filter";
if (currentFilter.label !== newLabel) {
setFilters((prev) =>
prev.map((f) =>
f.id === "customFilterId" ? { ...f, label: newLabel } : f,
),
);
}
}
}, [filters]);
useEffect(() => {
// Small delay to ensure the button is rendered
const timer = setTimeout(() => {
const button = document.querySelector(
`button[data-anv="filter-group-drawer-trigger"]`,
) as HTMLButtonElement;
if (button) {
button.click();
}
}, 100);
return () => clearTimeout(timer);
}, []);
return (
);
}
export default App;
```
#### Which fetching type is best for your case?
* Instant filtering is the generally preferred method, as it provides real-time feedback to users.
* Apply per-filter is preferred when performance is an issue, or if a user needs to build out a filter before needing to apply it.
* Instant and apply per-filter fetching should not be mixed. If per-filter is ever needed in one filter, the whole filter set should also use this method.
* Filters in the Drawer always use batch apply. No individual filter in the Drawer should have its own apply action.
* Batch filtering on the page is considered an edge case that requires a custom implementation.
### Content Guidelines
* All Filters need to have a label. This is the equivalent of a label found in traditional form elements.
* See each [individual filter type](#types-of-filters) for specific content guidelines.
