UI libraries / Algolia for Flutter / Widgets

Filter State

About this widget

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

There are three types of filters:

  • FilterFacet
  • FilterNumeric
  • FilterTag

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

  • A FilterOperator indicates which type of boolean operator should be applied between each filters in the group: FilterOperator.and or FilterOperator.or
  • An optional name Check out the Combining boolean operators guide for more information.
See code examples

Examples

Create

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

Copy 
1
2
3
4
5
6
7
8

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:

Copy 
1
2
3
4
5
6
7

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:

Copy 
1

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:

Copy 
1
2
3
4

  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

Copy 
1
2
3
4
5
6

  // Remove all filter groups
  filterState.clear(); 
   // Clear filter group 'authors'
  filterState.clear(authors);
  // Clear all filter groups except 'authors'
  filterState.clearExcept([authors]);

Fields

Parameter Description
filters
type: Stream<Filters>

Filters groups stream (facet, tag, numeric and hierarchical).
Copy 
1
2
3
4
5
6
7
8
9

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

Parameter Description
add

Adds a list of filters to a group by its groupID.
Copy 
1

filterState.add(groupID, filters);
set

Overrides filters list with a provided map.
Copy 
1

filterState.set(map);
remove

Removes a list of filters from a group by its groupID.
Copy 
1

filterState.remove(groupID, filters);
toggle

Toggles a filter in given group by its groupID.
Copy 
1

filterState.toggle(groupID, filter);
contains

Checks if a filter exists in a group.
Copy 
1

filterState.contains(groupID, filter);
addHierarchical

Adds a HierarchicalFilter to a group.
Copy 
1

filterState.addHierarchical(attribute, hierarchicalFilter);
removeHierarchical

Removes HierarchicalFilter group by its attribute.
Copy 
1

filterState.removeHierarchical(attribute);
clear

Clears provided group IDs. If none provided, all filters will be cleared.
Copy 
1

filterState.clear(groupIDs);
clearExcept

Clears all groups except provided group IDs.
Copy 
1

filterState.clearExcept(groupIDs);
modify

Asynchronously updates filters. Useful to apply multiple consecutive update operations without firing multiple filters events.
Copy 
1
2
3
4

filterState.modify((filters) async =>
      filters
          .add(groupID, filters)
          .remove(groupID, filters;
snapshot

Gets the latest Filters value submitted by filters:
Copy 
1

final filters = filterState.snapshot();
dispose

Releases all underlying resources
Copy 
1

filterState.dispose();
Did you find this page helpful?
Algolia for Flutter v0