🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / Algolia for Flutter / Widgets

Facet List

Signature 
FacetList(
  HitsSearcher searcher,
  FilterState filterState,
  String attribute,
  // Optional parameters
  FilterOperator operator,
  SelectionMode selectionMode,
  bool persistent,
)

FacetList.create(
  HitsSearcher searcher,
  FilterState filterState,
  String attribute,
  FilterGroupID groupID,
  // Optional parameters
  SelectionMode selectionMode,
  bool persistent,
}
See code examples
See live example

About this widget

FacetList is a filtering component that displays facets, and lets the user refine their search results by filtering on specific values.

Requirements

You need to add the attribute you provide to the widget in attributes for faceting, either on the dashboard or using the attributesForFaceting parameter with the API.

Examples

Create facet list

Create FacetList with given HitsSearcher and FilterState:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Create a FilterState
final filterState = FilterState();

// Create a HitsSearcher
final hitsSearcher = HitsSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
)..connectFilterState(filterState);

// Create a FacetList
final facetList = FacetList(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
);

Display facets

Get selectable facets changes by listening to facets submissions and call toggle to selected or deselect a facet value:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

StreamBuilder<List<SelectableFacet>>(
  stream: facetList.facets, // Listen to `facets` stream
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      final facets = snapshot.data ?? [];
      return ListView.builder(
        itemCount: facets.length,
        itemBuilder: (BuildContext context, int index) {
          final selectable = facets[index];
          final facet = selectable.item;
          return ListTile(
            title: Text('${facet.value} (${facet.count})'),
            trailing: selectable.isSelected ? const Icon(Icons.check) : null,
            onTap: () => facetList.toggle(facet.value), // Toggle a facet value on tap
          );
        },
      );
    } else {
      return const LinearProgressIndicator();
    }
  },
);

Dispose

Call dispose to release underlying resources:

Copy 
1

facetList.dispose();

Parameters

Parameter Description
searcher
type: HitsSearcher
Required

The HitsSearcher that handles your searches.
Copy 
1
2
3
4
5

final facetList = FacetList(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
);
filterState
type: FilterState
Required

The FilterState that holds your filters.
Copy 
1
2
3
4
5

final facetList = FacetList(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
);
attribute
type: String
Required

The attribute to filter.
Copy 
1
2
3
4
5

final facetList = FacetList(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
);
operator
type: FilterOperator
default: FilterOperator.or
Optional

Filters operator, which can either be FilterOperator.and or FilterOperator.or.
Copy 
1
2
3
4
5
6

final facetList = FacetList(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
  operator: FilterOperator.or,
);
groupID
type: FilterGroupID
Required

The identifier for the group of filters.
Copy 
1
2
3
4
5
6

final facetList = FacetList.create(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
  groupID: const FilterGroupID('YourAttribute', FilterOperator.or),
);
selectionMode
type: SelectionMode
default: SelectionMode.multiple
Optional

Whether the list can have SelectionMode.single or SelectionMode.multiple selections.
Copy 
1
2
3
4
5
6

final facetList = FacetList(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
  selectionMode: SelectionMode.multiple,
);
persistent
type: bool
default: false
Optional

When true, the selection will be kept even if it doesn’t match current results anymore.
Copy 
1
2
3
4
5
6

final facetList = FacetList(
  searcher: hitsSearcher,
  filterState: filterState,
  attribute: 'YourAttribute',
  persistent: true,
);

Fields

Parameter Description
facets
type: Stream<List<SelectableFacet>>

A stream of facets with their selection status.
Copy 
1
2
3
4
5

facetList.facets.listen((facets) {
  for (var facet in facets) {
    print("${facet.item} ${facet.isSelected ? 'x' : '-'}");
  }
});
eventTracker
type: FilterEventTracker

FilterEventTracker instance responsible for sending Insights events related to user interactions with facets, such as clicking, viewing, and converting filters. With the eventTracker, you can track user’s behavior, which can help you personalize their search experience.
Copy 
1
2
3
4
5

facetList.eventTracker.clickedFilters(
  indexName: 'your_index_name',
  eventName: 'your_event_name',
  values: ['value1', 'value2'],
);

Methods

Parameter Description
toggle

Select or deselect the provided facet value depending on the current selection state.
Copy 
1

facetList.toggle('blue');
snapshot

Gets the latest List<SelectableFacet> value submitted by facets:
Copy 
1

final selectableFacet = facetList.snapshot();
dispose

Releases all underlying resources
Copy 
1

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