> ## 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.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
{/* vale Algolia.HeadingPronouns = NO */}
## 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(
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
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(',')}"));
});
```
## Methods
Adds a list of filters to a group by its `groupID`.
```dart Dart icon=code theme={"system"}
filterState.add(groupID, filters);
```
Overrides `filters` list with a provided `map`.
```dart Dart icon=code theme={"system"}
filterState.set(map);
```
Removes a list of `filters` from a group by its `groupID`.
```dart Dart icon=code theme={"system"}
filterState.remove(groupID, filters);
```
Toggles a `filter` in given group by its `groupID`.
```dart Dart icon=code theme={"system"}
filterState.toggle(groupID, filter);
```
Checks if a `filter` exists in a group.
```dart Dart icon=code theme={"system"}
filterState.contains(groupID, filter);
```
Adds a `HierarchicalFilter` to a group.
```dart Dart icon=code theme={"system"}
filterState.addHierarchical(attribute, hierarchicalFilter);
```
Removes `HierarchicalFilter` group by its attribute.
```dart Dart icon=code theme={"system"}
filterState.removeHierarchical(attribute);
```
Clears provided group IDs.
If none provided, all filters will be cleared.
```dart Dart icon=code theme={"system"}
filterState.clear(groupIDs);
```
Clears all groups except provided group IDs.
```dart Dart icon=code theme={"system"}
filterState.clearExcept(groupIDs);
```
*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;
```
Gets the latest `Filters` value submitted by [`filters`](#param-filters):
```dart Dart icon=code theme={"system"}
final filters = filterState.snapshot();
```
Releases all underlying resources.
```dart Dart icon=code theme={"system"}
filterState.dispose();
```