> ## 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 and overflow 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`/`overflow` props. 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" justifyContent="space-between">
  <Toolbar associatedContent="invoice actions">
    <Toolbar.Button icon={SaveIcon} aria-label="Save" />
  </Toolbar>
  <FilterBar
    associatedContent="invoices"
    filters={filters}
    onFilterChange={setFilters}
  />
</Flex>
```

### 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 `size` and `overflow` props that were previously inherited from the parent Toolbar:

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

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