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

# FilterList (Facet)

> Shows a list of facet filters for refining search results.

```kotlin Signature theme={"system"}
FilterListConnector.Facet(
    filters: List<Filter.Facet>,
    filterState: FilterState,
    selectionMode: SelectionMode,
    groupID: FilterGroupID
)
```

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-android/tree/master/examples/android">
  Browse the FilterList (Facet) example code on GitHub.
</Card>

## About this widget

`FilterList.Facet` is a filtering view that displays any kind of [facet filters](/doc/api-reference/api-parameters/facetFilters) and lets users refine their search results by selecting them.

Compared to the [`RefinementList`](/doc/api-reference/widgets/refinement-list/android),
which takes its values from the search response facets, this widget displays facet filters that you add yourself.

## Examples

```kotlin Kotlin icon=code theme={"system"}
import com.algolia.instantsearch.filter.Filter

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val color = "color"
    val groupColor = groupAnd(color)
    val facetFilters = listOf(
        Filter.Facet(color, "red"),
        Filter.Facet(color, "green"),
        Filter.Facet(color, "blue"),
        Filter.Facet(color, "yellow"),
        Filter.Facet(color, "black")
    )
    val filterListConnector = FilterListConnector.Facet(
        filters = facetFilters,
        filterState = filterState,
        selectionMode = SelectionMode.Single,
        groupID = groupColor
    )
    val connection = ConnectionHandler(filterListConnector, searcher.connectFilterState(filterState))

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val filterListView: FilterListView.Facet = MyFilterListFacetAdapter() // your `FilterListView.Facet` implementation
        connection += filterListConnector.connectView(filterListView)
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}
```

### Low-level API

If you want to fully control the `FilterList.Facet` components and connect them manually, use the following components:

* `Searcher`: The [`Searcher`](/doc/api-reference/widgets/instantsearch/android) that handles your searches.
* `FilterState`: The current state of the filters.
* `FilterListViewModel.Facet`: The logic applied to the facet filters.
* `FilterListView.Facet`: The view that renders the facet filters.
* `FilterPresenter`: Optional. The presenter to customize the display of the filters.

```kotlin Kotlin icon=code theme={"system"}
import com.algolia.instantsearch.filter.Filter

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val color = "color"
    val filters = listOf(
        Filter.Facet(color, "red"),
        Filter.Facet(color, "green"),
        Filter.Facet(color, "blue"),
        Filter.Facet(color, "yellow"),
        Filter.Facet(color, "black")
    )
    val viewModel = FilterListViewModel.Facet(filters)
    val connection = ConnectionHandler()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val view: FilterListView.Facet = MyFilterListFacetAdapter() // your `FilterListView.Facet` implementation
        connection += searcher.connectFilterState(filterState)
        connection += viewModel.connectFilterState(filterState)
        connection += viewModel.connectView(view)

        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}
```

### Compose UI

InstantSearch provides the `FilterListState` as a state model, which is an implementation of the `FilterListView` interface.
You need to connect `FilterListState` to the `FilterListConnector` or `FilterListViewModel` like any other `FilterListView` implementation.

```kotlin Kotlin icon=code theme={"system"}
import com.algolia.instantsearch.filter.Filter

class MyActivity : AppCompatActivity() {
  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "YourIndexName"
  )
    val filterState = FilterState()
    val color = "color"
    val groupColor = groupAnd(color)
    val facetFilters = listOf(
        Filter.Facet(color, "red"),
        Filter.Facet(color, "green"),
        Filter.Facet(color, "blue"),
        Filter.Facet(color, "yellow"),
        Filter.Facet(color, "black")
    )
    val filterListState = FilterListState<Filter.Facet>()
    val filterListConnector = FilterListConnector.Facet(
        filters = facetFilters,
        filterState = filterState,
        selectionMode = SelectionMode.Single,
        groupID = groupColor
    )
    val connections = ConnectionHandler(filterListConnector)

    init {
        connections += searcher.connectFilterState(filterState)
        connections += filterListConnector.connectView(filterListState)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            filterListState.items.forEach { selectableFacet ->
                FilterRow( // your own UI composable to display `SelectableItem<Filter.Facet>`
                    selectableFilter = selectableFacet,
                    onClick = { filterListState.onSelection?.invoke(it) }
                )
            }
        }
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connections.disconnect()
        searcher.cancel()
    }
}
```

## Parameters

<ParamField body="filters" type="List<Filter.Facet>" post={["default: listOf()"]} required>
  The facet filters to display.
</ParamField>

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

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

<ParamField body="groupID" type="FilterGroupID" post={["default: FilterGroupID(FilterOperator.Or)"]}>
  The identifier for the group of filters.
</ParamField>

## View

<ParamField body="view" type="FilterListView.Facet">
  The view that renders the filters.

  ```kotlin Kotlin icon=code theme={"system"}
  import com.algolia.instantsearch.filter.Filter

  val view: FilterListView.Facet = MyFilterListFacetAdapter()
  filterListConnector.connectView(view)

  // Example of FilterListView.Facet implementation
  class MyFilterListFacetAdapter : FilterListView.Facet,
      ListAdapter<SelectableItem<Filter.Facet>, FilterListViewHolder>(DiffUtilItem()) {

      override var onSelection: Callback<Filter.Facet>? = null

      override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): FilterListViewHolder {
          return FilterListViewHolder(parent.inflate(R.layout.list_item_selectable))
      }

      override fun onBindViewHolder(holder: FilterListViewHolder, position: Int) {
          val (filter, selected) = getItem(position)
          holder.bind(FilterPresenterImpl()(filter), selected) { onSelection?.invoke(filter) }
      }

      override fun setItems(items: List<SelectableItem<Filter.Facet>>) {
          submitList(items)
      }
  }

  class DiffUtilItem<T : Filter> : DiffUtil.ItemCallback<SelectableItem<T>>() {
      override fun areItemsTheSame(oldItem: SelectableItem<T>, newItem: SelectableItem<T>): Boolean {
          return oldItem.first == newItem.first
      }

      override fun areContentsTheSame(oldItem: SelectableItem<T>, newItem: SelectableItem<T>): Boolean {
          return oldItem == newItem
      }
  }
  ```
</ParamField>