> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Facet List

> Shows a list of facets for refining search results.

```dart Signature theme={"system"}
HitsSearcher.buildFacetList(
  _FilterState_ filterState,
  String attribute,
  // Optional parameters
  _FilterOperator_ operator,
  _SelectionMode_ selectionMode,
  _bool_ persistent,
)

```

<Card title="View live demo" icon="monitor-play" href="https://algolia-flutter-showcase.netlify.app/#/?path=facet-list%2Fmultiple-facet-lists">
  Open the live Facet List example in your browser.
</Card>

## About this widget

`FacetList` is a filtering component that displays [facets](/doc/guides/managing-results/refine-results/filtering) and lets users refine their search results by filtering on specific values.

### Requirements

The [`attribute`](#param-attribute) provided to the widget must be in attributes for faceting,
either on the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or using the [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) parameter with the API.

## Examples

### Create facet list

Create `FacetList` with [`HitsSearcher`](/doc/api-reference/widgets/instantsearch/flutter)
and [`FilterState`](/doc/api-reference/widgets/filter-state/flutter):

```dart Dart icon=code theme={"system"}
// 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`](#param-facets) submissions.
Call [`toggle`](#param-toggle) to select or deselect a facet value:

```dart Dart icon=code theme={"system"}
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`](#param-dispose) to release underlying resources:

```dart Dart icon=code theme={"system"}
facetList.dispose();
```

## Parameters

<ParamField body="filterState" type="FilterState" required>
  The [`FilterState`](/doc/api-reference/widgets/filter-state/flutter) that holds your filters.
</ParamField>

<ParamField body="attribute" type="String" required>
  The attribute to filter.
</ParamField>

<ParamField body="operator" type="FilterOperator" post={["default: FilterOperator.or"]}>
  Filters operator, which can either be `FilterOperator.and` or `FilterOperator.or`.

  Use [filters or facet filters](/doc/guides/managing-results/refine-results/filtering/in-depth/filters-and-facetfilters)
  for more complex result refinement.
</ParamField>

<ParamField body="selectionMode" type="SelectionMode" post={["default: SelectionMode.multiple"]}>
  Whether the list can have `SelectionMode.single` or `SelectionMode.multiple` selections.
</ParamField>

<ParamField body="persistent" type="bool" default={false}>
  When `true`, the selection will be kept even if it doesn't match current results anymore.
</ParamField>

## Fields

<ParamField body="facets" type="Stream<List<SelectableFacet>>">
  A stream of facets with their selection status.

  ```dart Dart icon=code theme={"system"}
  facetList.facets.listen((facets) {
    for (var facet in facets) {
      print("${facet.item} ${facet.isSelected ? 'x' : '-'}");
    }
  });
  ```
</ParamField>

<ParamField body="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.

  ```dart Dart icon=code theme={"system"}
  facetList.eventTracker.clickedFilters(
    indexName: 'INDEX_NAME',
    eventName: 'your_event_name',
    values: ['value1', 'value2'],
  );
  ```
</ParamField>

## Methods

<ParamField body="toggle">
  Select or deselect the provided facet value depending on the current selection state.

  ```dart Dart icon=code theme={"system"}
  facetList.toggle('blue');
  ```
</ParamField>

<ParamField body="snapshot">
  Gets the latest `List<SelectableFacet>` value submitted by [`facets`](#param-facets):

  ```dart Dart icon=code theme={"system"}
  final selectableFacet = facetList.snapshot();
  ```
</ParamField>

<ParamField body="dispose">
  Releases all underlying resources.

  ```dart Dart icon=code theme={"system"}
  facetList.dispose();
  ```
</ParamField>