> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# FilterCascade

A filter over a hierarchy — organization › deployment › application, region › zone. The same 36px pill as `FilterDropdown`; each level opens as its own panel beside the option that opened it, and an item at any depth can be picked. The trigger reads the path: «Scope ● a › ● b», the tooltip carries it whole. Items are the consumer’s own objects, read through accessors; a level can load when it is first opened (`loadChildren`), and `parentLabel` adds the option that picks the level’s parent — «Deployment level». The search finds items at every depth. Compose the panels with `FilterCascadeLevels` to add group labels and options set apart; with no children, `FilterCascadeContent` renders the levels by itself. Reach for `FilterDropdown` when the values are flat.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/FilterCascade) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/patterns-filtercascade--overview)

```tsx
import { FilterCascade, FilterCascadeContent, FilterCascadeTrigger } from '@wallarm-org/design-system/FilterCascade';

export const Default = () => (
  <FilterCascade label='Region' collection={regions} data-testid='filter-cascade'>
    <FilterCascadeTrigger />
    <FilterCascadeContent />
  </FilterCascade>
);
```

## Usage

```tsx
import { FilterCascade, FilterCascadeContent, FilterCascadeTrigger } from '@wallarm-org/design-system/FilterCascade';
```

## Examples

### Scope filter

The Scope filter of Flow management: lazy applications, «Deployment level», search, toggle.

```tsx
import { useState } from 'react';
import { FilterCascade, FilterCascadeClear, FilterCascadeTrigger } from '@wallarm-org/design-system/FilterCascade';

export const ScopeFilter = () => {
  const [value, setValue] = useState<string[]>([]);
  return (
    <div className='flex flex-col gap-12'>
      <FilterCascade
        label='Scope'
        collection={scopes}
        loadChildren={loadApplications}
        parentLabel='Deployment level'
        value={value}
        onValueChange={details => setValue(details.value)}
        data-testid='filter-cascade-scope'
      >
        <FilterCascadeTrigger>
          <FilterCascadeClear data-analytics-id='SCOPE_CLEAR' />
        </FilterCascadeTrigger>
        <ScopeMenu />
      </FilterCascade>
      <code className='text-xs text-text-secondary'>value: {JSON.stringify(value)}</code>
    </div>
  );
};
```

### Picked

A picked application: the trigger reads the path; only the deployment segment truncates.

```tsx
import { FilterCascade, FilterCascadeContent, FilterCascadeTrigger } from '@wallarm-org/design-system/FilterCascade';

export const Picked = () => (
  <FilterCascade
    label='Scope'
    collection={longCollection}
    loadChildren={async (): Promise<Scope[]> => [
      { kind: 'application', uid: 'checkout', name: 'checkout-api' },
    ]}
    defaultValue={['eu1', 'checkout']}
    data-testid='filter-cascade-picked'
  >
    <FilterCascadeTrigger />
    <FilterCascadeContent />
  </FilterCascade>
);
```

### Parent picked

The deployment itself, picked through «Deployment level».

```tsx
import { FilterCascade, FilterCascadeTrigger } from '@wallarm-org/design-system/FilterCascade';

export const ParentPicked = () => (
  <FilterCascade
    label='Scope'
    collection={scopes}
    loadChildren={loadApplications}
    parentLabel='Deployment level'
    defaultValue={['staging-us']}
    data-testid='filter-cascade-parent'
  >
    <FilterCascadeTrigger />
    <ScopeMenu withToggle={false} />
  </FilterCascade>
);
```

### Load error

A level that fails to load offers a retry.

```tsx
import { FilterCascade, FilterCascadeTrigger } from '@wallarm-org/design-system/FilterCascade';

export const LoadError = () => (
  <FilterCascade
    label='Scope'
    collection={scopes}
    loadChildren={() => Promise.reject(new Error('Unavailable'))}
    parentLabel='Deployment level'
    data-testid='filter-cascade-error'
  >
    <FilterCascadeTrigger />
    <ScopeMenu withToggle={false} />
  </FilterCascade>
);
```

### Disabled

```tsx
import { FilterCascade, FilterCascadeContent, FilterCascadeTrigger } from '@wallarm-org/design-system/FilterCascade';

export const Disabled = () => (
  <FilterCascade
    label='Region'
    collection={regions}
    defaultValue={['eu', 'fra']}
    disabled
    data-testid='filter-cascade-disabled'
  >
    <FilterCascadeTrigger />
    <FilterCascadeContent />
  </FilterCascade>
);
```

## Props

| Prop            | Type                                                                   | Default                    | Description                                                                                                                                                                                    |
| --------------- | ---------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| label \*        | `string`                                                               |                            | Attribute name: the trigger text, its aria-label, «Clear \{label}», «Search \{label}».                                                                                                         |
| collection \*   | `FilterCascadeCollection<T>`                                           |                            | From `createFilterCascadeCollection`.                                                                                                                                                          |
| value           | `string[] \| undefined`                                                |                            | Controlled path, top level first; `[]` = unset.                                                                                                                                                |
| defaultValue    | `string[] \| undefined`                                                |                            |                                                                                                                                                                                                |
| onValueChange   | `((details: FilterCascadeValueChangeDetails<T>) => void) \| undefined` |                            |                                                                                                                                                                                                |
| open            | `boolean \| undefined`                                                 |                            |                                                                                                                                                                                                |
| defaultOpen     | `boolean \| undefined`                                                 |                            |                                                                                                                                                                                                |
| onOpenChange    | `((open: boolean) => void) \| undefined`                               |                            |                                                                                                                                                                                                |
| loadChildren    | `((item: T, path: string[]) => Promise<T[]>) \| undefined`             |                            | Loads the next level of an item the collection marks with `hasChildren` — when the item is first highlighted, or when it is on the picked path.                                                |
| parentLabel     | `string \| ((item: T) => string) \| undefined`                         |                            | Puts an option at the top of every next level that picks the item which opened it — «Deployment level». With it, a row that opens a level only opens it; without it, the row itself is picked. |
| searchIn        | `"all" \| "top" \| undefined`                                          | `all`                      | What the search matches: every loaded level, as one list with each match's path (`'all'`), or the top level only, its levels still opening beside it (`'top'`).                                |
| searchThreshold | `number \| undefined`                                                  | `DEFAULT_SEARCH_THRESHOLD` | Top-level option count from which `FilterCascadeSearch` renders.                                                                                                                               |
| disabled        | `boolean \| undefined`                                                 | `false`                    |                                                                                                                                                                                                |
| title           | `string \| undefined`                                                  |                            |                                                                                                                                                                                                |
| defaultChecked  | `boolean \| undefined`                                                 |                            |                                                                                                                                                                                                |
| autoFocus       | `boolean \| undefined`                                                 |                            |                                                                                                                                                                                                |
| id              | `string \| undefined`                                                  |                            |                                                                                                                                                                                                |
| tabIndex        | `number \| undefined`                                                  |                            |                                                                                                                                                                                                |
| rel             | `string \| undefined`                                                  |                            |                                                                                                                                                                                                |
| data-testid     | `string \| undefined`                                                  |                            |                                                                                                                                                                                                |

### FilterCascadeClear

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| disabled       | `boolean \| undefined`                               |         |             |
| name           | `string \| undefined`                                |         |             |
| type           | `"button" \| "submit" \| "reset" \| undefined`       |         |             |
| value          | `string \| number \| readonly string[] \| undefined` |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |

### FilterCascadeContent

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |

### FilterCascadeItem

| Prop           | Type                                                 | Default | Description                                                                  |
| -------------- | ---------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| item \*        | `FilterCascadeEntry<unknown>`                        |         | An entry of a level's `items` (or its `parentItem`) from `useFilterCascade`. |
| defaultChecked | `boolean \| undefined`                               |         |                                                                              |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |                                                                              |
| autoFocus      | `boolean \| undefined`                               |         |                                                                              |
| id             | `string \| undefined`                                |         |                                                                              |
| tabIndex       | `number \| undefined`                                |         |                                                                              |
| title          | `string \| undefined`                                |         |                                                                              |
| rel            | `string \| undefined`                                |         |                                                                              |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |                                                                              |
| data-testid    | `string \| undefined`                                |         |                                                                              |

### FilterCascadeEmpty

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |

### FilterCascadeGroupLabel

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |

### FilterCascadeItems

| Prop   | Type                                                            | Default | Description                                                     |
| ------ | --------------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| filter | `((item: FilterCascadeEntry<unknown>) => boolean) \| undefined` |         | Which of the level's options to render; all of them by default. |

### FilterCascadeLevel

| Prop           | Type                                                 | Default | Description                                   |
| -------------- | ---------------------------------------------------- | ------- | --------------------------------------------- |
| level \*       | `FilterCascadeLevelData<unknown>`                    |         | An entry of `levels` from `useFilterCascade`. |
| defaultChecked | `boolean \| undefined`                               |         |                                               |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |                                               |
| autoFocus      | `boolean \| undefined`                               |         |                                               |
| id             | `string \| undefined`                                |         |                                               |
| tabIndex       | `number \| undefined`                                |         |                                               |
| title          | `string \| undefined`                                |         |                                               |
| rel            | `string \| undefined`                                |         |                                               |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |                                               |
| data-testid    | `string \| undefined`                                |         |                                               |

### FilterCascadeParentItem

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| title          | `string \| undefined`                                |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |

### FilterCascadeSearch

| Prop           | Type                                                 | Default | Description                                                                     |
| -------------- | ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| onChange       | `((query: string) => void) \| undefined`             |         | Called after the query changes; the root owns the query itself.                 |
| title          | `string \| undefined`                                |         |                                                                                 |
| pattern        | `string \| undefined`                                |         |                                                                                 |
| defaultChecked | `boolean \| undefined`                               |         |                                                                                 |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |                                                                                 |
| autoFocus      | `boolean \| undefined`                               |         |                                                                                 |
| id             | `string \| undefined`                                |         |                                                                                 |
| tabIndex       | `number \| undefined`                                |         |                                                                                 |
| rel            | `string \| undefined`                                |         |                                                                                 |
| disabled       | `boolean \| undefined`                               |         |                                                                                 |
| name           | `string \| undefined`                                |         |                                                                                 |
| alt            | `string \| undefined`                                |         |                                                                                 |
| height         | `string \| number \| undefined`                      |         |                                                                                 |
| src            | `string \| undefined`                                |         |                                                                                 |
| width          | `string \| number \| undefined`                      |         |                                                                                 |
| autoComplete   | `HTMLInputAutoCompleteAttribute \| undefined`        |         |                                                                                 |
| maxLength      | `number \| undefined`                                |         |                                                                                 |
| minLength      | `number \| undefined`                                |         |                                                                                 |
| placeholder    | `string \| undefined`                                |         |                                                                                 |
| readOnly       | `boolean \| undefined`                               |         |                                                                                 |
| required       | `boolean \| undefined`                               |         |                                                                                 |
| checked        | `boolean \| undefined`                               |         |                                                                                 |
| step           | `string \| number \| undefined`                      |         |                                                                                 |
| accept         | `string \| undefined`                                |         |                                                                                 |
| max            | `string \| number \| undefined`                      |         |                                                                                 |
| min            | `string \| number \| undefined`                      |         |                                                                                 |
| multiple       | `boolean \| undefined`                               |         |                                                                                 |
| onClear        | `(() => void) \| undefined`                          |         | Called when the built-in clear button empties the field, before `onChange('')`. |
| data-testid    | `string \| undefined`                                |         |                                                                                 |

### FilterCascadeCheckboxItem

| Prop            | Type                                                 | Default | Description                                                      |
| --------------- | ---------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| checked \*      | `boolean`                                            |         |                                                                  |
| onCheckedChange | `((checked: boolean) => void) \| undefined`          |         |                                                                  |
| icon            | `ReactNode`                                          |         | Before the label, in the options' 16px icon slot — a status dot. |
| title           | `string \| undefined`                                |         |                                                                  |
| defaultChecked  | `boolean \| undefined`                               |         |                                                                  |
| defaultValue    | `string \| number \| readonly string[] \| undefined` |         |                                                                  |
| autoFocus       | `boolean \| undefined`                               |         |                                                                  |
| id              | `string \| undefined`                                |         |                                                                  |
| tabIndex        | `number \| undefined`                                |         |                                                                  |
| rel             | `string \| undefined`                                |         |                                                                  |
| type            | `"button" \| "submit" \| "reset" \| undefined`       |         |                                                                  |
| disabled        | `boolean \| undefined`                               |         |                                                                  |
| name            | `string \| undefined`                                |         |                                                                  |
| value           | `string \| number \| readonly string[] \| undefined` |         |                                                                  |
| data-testid     | `string \| undefined`                                |         |                                                                  |

### FilterCascadeSection

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |

### FilterCascadeTrigger

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| title          | `string \| undefined`                                |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| type           | `"button" \| "submit" \| "reset" \| undefined`       |         |             |
| disabled       | `boolean \| undefined`                               |         |             |
| name           | `string \| undefined`                                |         |             |
| value          | `string \| number \| readonly string[] \| undefined` |         |             |
| data-testid    | `string \| undefined`                                |         |             |