Skip to main content
Signature
HitsSearcher.buildFacetList(
  _FilterState_ filterState,
  String attribute,
  // Optional parameters
  _FilterOperator_ operator,
  _SelectionMode_ selectionMode,
  _bool_ persistent,
)
View demo

​
About this widget

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

​
Requirements

The attribute provided to the widget must be in attributes for faceting, either on the dashboard or using the attributesForFaceting parameter with the API.

​
Examples

​
Create facet list

Create FacetList with HitsSearcher and FilterState:
Dart
// 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 facet changes by listening to facets submissions. Call toggle to select or deselect a facet value:
Dart
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:
Dart
facetList.dispose();

​
Parameters

​
filterState
FilterState
required
The FilterState that holds your filters.
​
attribute
String
required
The attribute to filter.
​
operator
FilterOperator
default: FilterOperator.or
Filters operator, which can either be FilterOperator.and or FilterOperator.or.Use filters or facet filters for more complex result refinement.
​
selectionMode
SelectionMode
default: SelectionMode.multiple
Whether the list can have SelectionMode.single or SelectionMode.multiple selections.
​
persistent
bool
default:false
When true, the selection will be kept even if it doesn’t match current results anymore.

​
Fields

​
facets
Stream<List<SelectableFacet>>
A stream of facets with their selection status.
Dart
facetList.facets.listen((facets) {
  for (var facet in facets) {
    print("${facet.item} ${facet.isSelected ? 'x' : '-'}");
  }
});
​
eventTracker
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.
Dart
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.
Dart
facetList.toggle('blue');
​
snapshot
Gets the latest List<SelectableFacet> value submitted by facets:
Dart
final selectableFacet = facetList.snapshot();
​
dispose
Releases all underlying resources.
Dart
facetList.dispose();