Algolia DevCon
Oct. 2–3 2024, virtual.
UI libraries / Algolia for Flutter / Widgets

Facet List

Signature 
HitsSearcher.buildFacetList(
  _FilterState_ filterState,
  String attribute,
  // Optional parameters
  _FilterOperator_ operator,
  _SelectionMode_ selectionMode,
  _bool_ persistent,
)
See code examples
See live example

About this widget

FacetList is a filtering component that displays facets, and lets users 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

// 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 = hitsSearcher.buildFacetList(
  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

filterState
type: FilterState
Required

The FilterState that holds your filters.
attribute
type: String
Required

The attribute to filter.
operator
type: FilterOperator
default: FilterOperator.or
Optional

Filters operator, which can either be FilterOperator.and or FilterOperator.or.
selectionMode
type: SelectionMode
default: SelectionMode.multiple
Optional

Whether the list can have SelectionMode.single or SelectionMode.multiple selections.
persistent
type: bool
default: false
Optional

When true, the selection will be kept even if it doesn’t match current results anymore.

Fields

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

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 v1