> ## Documentation Index
> Fetch the complete documentation index at: https://www.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] [Explore example code](https://github.com/algolia/instantsearch-android/tree/master/examples/android)
>
> Browse the FilterList (Facet) example code on GitHub.

## About this widget

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

Compared to the [`RefinementList`](https://www.algolia.com/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`](https://www.algolia.com/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

**filters** `List\<Filter.Facet\>` *required*

The facet filters to display.

**filterState** `FilterState` *required*

The [`FilterState`](https://www.algolia.com/doc/api-reference/widgets/filter-state/android) that will hold your filters.

**selectionMode** `SelectionMode`

Whether the list can have `Single` or `Multiple` selections.

**groupID** `FilterGroupID`

The identifier for the group of filters.

## View

**view** `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
    }
}
```
