> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FilterState

> Provides interface for managing applied filters.

## About this widget

A `FilterState` holds one or several filters,
organized in groups,
and emits changes of added or removed filters,
which are applied to searches performed by connected components.

You can add [three types of filters](/doc/guides/managing-results/refine-results/filtering):

* `FilterFacet`
* `FilterNumeric`
* `FilterTag`

A group of filters must be identified by a `FilterGroupID`.
A `FilterGroupID` has:

* An optional `name`
* A `FilterOperator` indicating which type of boolean operator should be applied between each filter in the group: `FilterOperator.and` or `FilterOperator.or`.
  For more information, see [Combining boolean operators](/doc/guides/managing-results/refine-results/filtering/in-depth/combining-boolean-operators).

## Examples

### Create

The following is an example of creating and setting up a `FilterState`
with different filters (facets, tags and numerical):

```dart Dart icon=code theme={"system"}
const authors = FilterGroupID('author', FilterOperator.or);
const genres = FilterGroupID('genres');
const numbers = FilterGroupID('numbers');
final filterState = FilterState()
  ..add(authors, [Filter.facet('author', 'Shakespeare')])
  ..add(genres, [Filter.tag('drama')])
  ..add(numbers, [Filter.range('rating', lowerBound: 3, upperBound: 5)])
  ..add(numbers, [Filter.comparison('price', NumericOperator.less, 50)]);
```

The preceding code snippet corresponds to the following expression:
`(author:Shakespeare) AND (_tags:drama) AND (rating:3 TO 5 AND price < 50)`

### Read

Listen to [`filters`](#param-filters) stream to get filtering changes:

```dart Dart icon=code theme={"system"}
StreamBuilder<Filters>(
  stream: filterState.filters,
  builder: (context, snapshot) {
    final filters = snapshot.data;
    final count = filters?.getFilters().length ?? 0;
    return Text('Filters applied: $count');
  });
```

Use [`snapshot`](#param-snapshot) to get the latest `Filters` value submitted by [`filters`](#param-filters) stream:

```dart Dart icon=code theme={"system"}
final filters = filterState.snapshot();
```

### Update

`FilterState` can be updated using methods such as [`add`](#param-add), [`set`](#param-set)
and [`remove`](#param-remove), each modification triggers a [`filters`](#param-filters) submission.
Use [`modify`](#param-modify) to run multiple modifications (atomically), and trigger a single [`filters`](#param-filters)
submission:

```dart Dart icon=code theme={"system"}
filterState.modify((filters) async =>
    filters
        .add(authors, [Filter.facet('author', 'J. K. Rowling')])
        .remove(authors, [Filter.facet('author', 'Shakespeare')]));
```

### Delete

Remove all or some filter groups using [`clear`](#param-clear) and [`clearExcept`](/doc/api-reference/widgets/filter-state/flutter#param-clear-except):

```dart Dart icon=code theme={"system"}
// Remove all filter groups
filterState.clear(); 
 // Clear filter group 'authors'
filterState.clear(authors);
// Clear all filter groups except 'authors'
filterState.clearExcept([authors]); 
```

## Fields

<ParamField body="filters" type="Stream<Filters>">
  Filters groups stream (facet, tag, numeric and hierarchical).

  ```dart Dart icon=code theme={"system"}
  filterState.filters.listen((filters) {
    // Count of applied filters
    final count = filters.getFilters().length;
    print('${count} filter(s) applied');

    // Applied facet filters
    filters.facetGroups.forEach(
        (key, value) => print("${key.name}: ${value.join(',')}"));
  });
  ```
</ParamField>

## Methods

<ParamField body="add">
  Adds a list of filters to a group by its `groupID`.

  ```dart Dart icon=code theme={"system"}
  filterState.add(groupID, filters);
  ```
</ParamField>

<ParamField body="set">
  Overrides `filters` list with a provided `map`.

  ```dart Dart icon=code theme={"system"}
  filterState.set(map);
  ```
</ParamField>

<ParamField body="remove">
  Removes a list of `filters` from a group by its `groupID`.

  ```dart Dart icon=code theme={"system"}
  filterState.remove(groupID, filters);
  ```
</ParamField>

<ParamField body="toggle">
  Toggles a `filter` in given group by its `groupID`.

  ```dart Dart icon=code theme={"system"}
  filterState.toggle(groupID, filter);
  ```
</ParamField>

<ParamField body="contains">
  Checks if a `filter` exists in a group.

  ```dart Dart icon=code theme={"system"}
  filterState.contains(groupID, filter);
  ```
</ParamField>

<ParamField body="addHierarchical">
  Adds a `HierarchicalFilter` to a group.

  ```dart Dart icon=code theme={"system"}
  filterState.addHierarchical(attribute, hierarchicalFilter);
  ```
</ParamField>

<ParamField body="removeHierarchical">
  Removes `HierarchicalFilter` group by its attribute.

  ```dart Dart icon=code theme={"system"}
  filterState.removeHierarchical(attribute);
  ```
</ParamField>

<ParamField body="clear">
  Clears provided group IDs.
  If none provided, all filters will be cleared.

  ```dart Dart icon=code theme={"system"}
  filterState.clear(groupIDs);
  ```
</ParamField>

<ParamField body="clearExcept">
  Clears all groups except provided group IDs.

  ```dart Dart icon=code theme={"system"}
  filterState.clearExcept(groupIDs);
  ```
</ParamField>

<ParamField body="modify">
  *Asynchronously* updates [`filters`](#param-filters).
  Useful to apply multiple consecutive update operations without firing multiple filters events.

  ```dart Dart icon=code theme={"system"}
  filterState.modify((filters) async =>
    filters
        .add(groupID, filters)
        .remove(groupID, filters;
  ```
</ParamField>

<ParamField body="snapshot">
  Gets the latest `Filters` value submitted by [`filters`](#param-filters):

  ```dart Dart icon=code theme={"system"}
  final filters = filterState.snapshot();
  ```
</ParamField>

<ParamField body="dispose">
  Releases all underlying resources.

  ```dart Dart icon=code theme={"system"}
  filterState.dispose();
  ```
</ParamField>