UI libraries / Algolia for Flutter / Widgets

Facet List

Signature 
FacetList(
  Stream<List<Facet>> facetsStream,
  SelectionState state,
  String attribute,
  // Optional parameters
  SelectionMode selectionMode,
  bool persistent,
  FilterEventTracker? eventTracker,
)

FacetList.create(
  Stream<List<Facet>> facetsStream,
  SelectionState state,
  String attribute,
  // Optional parameters
  SelectionMode selectionMode,
  bool persistent,
  FilterEventTracker? eventTracker,
}
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

Parameter Description
facetsStream
type: Stream<List<Facet>>
Required

Stream of facets usually fetched from HitsSearcher’s latest search response. It provides an up-to-date list of facets based on the current search context, which the FacetList uses to display the available facet options.
state
type: SelectionState
Required

Manages the facet selection state, usually handled by FilterState. This state keeps track of the facets that are currently selected and updates the selection as user interactions occur.
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

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