> ## 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.

# Toolbar.Filters to FilterBar

> Guide for migrating from Toolbar.Filters to the standalone FilterBar component.

export const VersionStatus = ({version}) => {
  const isUnreleased = version === "unreleased";
  return <Badge color={isUnreleased ? "orange" : "green"}>
      {isUnreleased ? "Unreleased" : `v${version}`}
    </Badge>;
};

<VersionStatus version="3.0.1" />

<Note>
  This guide covers changes to the **beta** FilterBar component (previously
  Toolbar.Filters). These APIs may continue to evolve before the stable release.
</Note>

## Overview

`Toolbar.Filters` has been removed as a compound sub-component of `Toolbar`. Use the standalone `FilterBar` component instead.

## Design Rationale

### Why separate FilterBar from Toolbar?

Previously, filters were tightly coupled to Toolbar as `Toolbar.Filters`, requiring a wrapping `<Toolbar>` even when no toolbar actions were needed. This coupling:

* Forced filters to inherit Toolbar's size settings
* Prevented filters and toolbars from evolving independently
* Required a parent Toolbar for filters to function

The standalone `FilterBar` has its own `role="toolbar"`, keyboard navigation, and `size` prop. When used alongside a Toolbar, compose them as siblings via Flex layout. Standard ARIA patterns handle keyboard traversal -- Tab moves between the two toolbars, arrow keys navigate within each.

## Migration Guide

### Standalone filters (no toolbar actions)

```tsx theme={null}
// Before
<Toolbar associatedContent="invoices">
  <Toolbar.Filters
    filters={filters}
    onFilterChange={setFilters}
  />
</Toolbar>

// After
<FilterBar
  associatedContent="invoices"
  filters={filters}
  onFilterChange={setFilters}
/>
```

### Filters with toolbar actions

```tsx theme={null}
// Before
<Toolbar associatedContent="invoices">
  <Toolbar.Filters
    filters={filters}
    onFilterChange={setFilters}
  />
  <Toolbar.ControlGroup>
    <Toolbar.Button icon={SaveIcon} aria-label="Save" />
  </Toolbar.ControlGroup>
</Toolbar>

// After
<Flex alignItems="center" style={{ width: "100%" }}>
  <FilterBar
    associatedContent="invoices"
    filters={filters}
    flexGrow={1}
    onFilterChange={setFilters}
  />
  <Toolbar
    associatedContent="invoice actions"
    style={{ flex: "0 0 auto", width: "fit-content" }}
  >
    <Toolbar.Button icon={SaveIcon} aria-label="Save" />
  </Toolbar>
</Flex>
```

Constrain the Toolbar with `flex: "0 0 auto"` and `width: "fit-content"`, and give FilterBar `flexGrow={1}`. Without those, the Toolbar expands and forces filters to collapse. See the live example under [Filters with Additional Toolbar Items](/docs/web/components/filter-bar/code#filters-with-additional-toolbar-items).

### Import changes

```tsx theme={null}
// Before
import { Toolbar, type Filter } from "@servicetitan/anvil2/beta";

// After
import { FilterBar, Toolbar, type Filter } from "@servicetitan/anvil2/beta";
```

### New required prop: `associatedContent`

`FilterBar` requires an `associatedContent` string prop for accessibility. It populates the `aria-label` on the filter bar's `role="toolbar"` element.

```tsx theme={null}
<FilterBar
  associatedContent="invoices" // Required -- describes what this filter bar filters
  filters={filters}
  onFilterChange={setFilters}
/>
```

### Optional new props

`FilterBar` accepts a `size` prop that was previously inherited from the parent Toolbar:

```tsx theme={null}
<FilterBar
  associatedContent="invoices"
  filters={filters}
  onFilterChange={setFilters}
  size="small" // Default: "xsmall"
/>
```

## Breaking Changes

<Warning>
  These changes require code updates before upgrading. The previous API is no
  longer supported.
</Warning>

* `Toolbar.Filters` has been **removed** -- Use the standalone `FilterBar` component instead.
* `FilterBar` requires a new `associatedContent` prop (string) for accessibility.
* Filter types (`Filter`, `BooleanFilter`, etc.) are now exported from `FilterBar`, not `Toolbar`.

### Why Breaking?

As a beta API, `Toolbar.Filters` was removed directly without a deprecation path. The standalone `FilterBar` provides a clearer API surface and independent evolution path for both components.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.