Skip to main content

​
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:
  • 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.

​
Examples

​
Create

The following is an example of creating and setting up a FilterState with different filters (facets, tags and numerical):
Dart
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 stream to get filtering changes:
Dart
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 to get the latest Filters value submitted by filters stream:
Dart
final filters = filterState.snapshot();

​
Update

FilterState can be updated using methods such as add, set and remove, each modification triggers a filters submission. Use modify to run multiple modifications (atomically), and trigger a single filters submission:
Dart
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 and clearExcept:
Dart
// Remove all filter groups
filterState.clear(); 
 // Clear filter group 'authors'
filterState.clear(authors);
// Clear all filter groups except 'authors'
filterState.clearExcept([authors]);

​
Fields

​
filters
Stream<Filters>
Filters groups stream (facet, tag, numeric and hierarchical).
Dart
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

​
add
Adds a list of filters to a group by its groupID.
Dart
filterState.add(groupID, filters);
​
set
Overrides filters list with a provided map.
Dart
filterState.set(map);
​
remove
Removes a list of filters from a group by its groupID.
Dart
filterState.remove(groupID, filters);
​
toggle
Toggles a filter in given group by its groupID.
Dart
filterState.toggle(groupID, filter);
​
contains
Checks if a filter exists in a group.
Dart
filterState.contains(groupID, filter);
​
addHierarchical
Adds a HierarchicalFilter to a group.
Dart
filterState.addHierarchical(attribute, hierarchicalFilter);
​
removeHierarchical
Removes HierarchicalFilter group by its attribute.
Dart
filterState.removeHierarchical(attribute);
​
clear
Clears provided group IDs. If none provided, all filters will be cleared.
Dart
filterState.clear(groupIDs);
​
clearExcept
Clears all groups except provided group IDs.
Dart
filterState.clearExcept(groupIDs);
​
modify
Asynchronously updates filters. Useful to apply multiple consecutive update operations without firing multiple filters events.
Dart
filterState.modify((filters) async =>
  filters
      .add(groupID, filters)
      .remove(groupID, filters;
​
snapshot
Gets the latest Filters value submitted by filters:
Dart
final filters = filterState.snapshot();
​
dispose
Releases all underlying resources.
Dart
filterState.dispose();