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

# RefinementList

> Shows a list of facets for refining search results.

```kotlin Signature theme={"system"}
FacetListConnector(
    searcher: HitsSearcher,
    filterState: FilterState,
    attribute: String,
    selectionMode: SelectionMode,
    items: List<FacetHits>,
    persistentSelection: Boolean,
    groupID: FilterGroupID,
)
```

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

## About this widget

`RefinementList` is a filtering view 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

```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {

  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "YourIndexName"
  )
  val facetList = FacetListConnector(
      searcher = searcher,
      filterState = FilterState(),
      attribute = "facetName",
      selectionMode = SelectionMode.Multiple
  )
  val connection = ConnectionHandler(facetList)

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      // You can use the default `FacetListAdapter`, or implement your own UI component that implements the `FacetListView` interface.
      val facetListAdapter = FacetListAdapter(FacetListViewHolderImpl.Factory)
      connection += facetList.connectView(facetListAdapter)
      searcher.searchAsync()
  }

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

### Low-level API

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

* `FilterState`. The current state of the filters.
* `FacetListViewModel`. The logic applied to the facets.
* `FacetListView`. The view that renders facets.
* `FacetListPresenter`. Optional. The presenter that controls the sorting and other settings of the facet list view.

```kotlin Kotlin icon=code theme={"system"}
class MyActivity: AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val attribute = "facetName"
    val viewModel = FacetListViewModel()
    val presenter = FacetListPresenterImpl(listOf(FacetSortCriterion.CountDescending), limit = 5)
    val connection = ConnectionHandler()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // You can use the default FacetListAdapter, or write your own UI component that implements the FacetListView interface.
        val view: FacetListView = FacetListAdapter(MyFacetListViewHolder.Factory)

        connection += searcher.connectFilterState(filterState)
        connection += viewModel.connectFilterState(filterState, attribute, FilterOperator.Or)
        connection += viewModel.connectSearcher(searcher, attribute)
        connection += viewModel.connectView(view, presenter)

        searcher.searchAsync()
    }

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

### Compose UI

InstantSearch provides the `FacetListState` as a state model,
which is an implementation of the `FacetListView` interface.
You need to connect `FacetListState` to the `FacetListConnector` or `FacetListViewModel` like any other `FacetListView` implementation.

```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val facetListState = FacetListState()
    val facetList = FacetListConnector(
        searcher = searcher,
        filterState = FilterState(),
        attribute = "facetName",
        selectionMode = SelectionMode.Multiple
    )
    val connections = ConnectionHandler(facetList)

    init {
        connections += facetList.connectView(facetListState)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // You can use the default `FacetListAdapter`, or implement your own UI component that implements the `FacetListView` interface.
        setContent {
            facetListState.items.forEach { selectableFacet ->
                FacetRow( // your own UI composable to display `SelectableItem<FacetHits>`
                    selectableFacet = selectableFacet,
                    onClick = { facet -> facetListState.onSelection?.invoke(facet) }
                )
            }
        }
        searcher.searchAsync()
    }

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

## Parameters

<ParamField body="searcher" type="HitsSearcher" required>
  The [`Searcher`](/doc/api-reference/widgets/instantsearch/android#hitssearcher) that handles your searches.
</ParamField>

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

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

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

<ParamField body="items" type="List<FacetHits>" post={["default: listOf()"]}>
  If specified, the default facet values to display.
</ParamField>

<ParamField body="persistentSelection" type="Boolean" default={false}>
  When true, the selection will be kept even if it does not match current results anymore.
</ParamField>

<ParamField body="groupID" type="FilterGroupID" post={["default: FilterGroupID(attribute, 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>

## View

<ParamField body="view" type="FacetListView" required>
  The view that renders the facets.
</ParamField>

<ParamField body="presenter" type="FacetListPresenter" default="null">
  The presenter that controls the sorting and other settings of the facet list view.

  ```kotlin Kotlin icon=code theme={"system"}
  val facetListAdapter = FacetListAdapter(FacetListViewHolderImpl.Factory)
  val facetListPresenter = FacetListPresenterImpl(listOf(FacetSortCriterion.CountDescending, FacetSortCriterion.AlphabeticalAscending))
  facetListCategory.connectView(facetListAdapter, facetListPresenter)
  ```
</ParamField>

## Presenter

<ParamField body="sortBy" type="List<FacetSortCriterion>" default="listOf(FacetSortCriterion.CountDescending)">
  How to sort facets. Must be one or more of the following values:

  * `FacetSortCriterion.IsRefined`
  * `FacetSortCriterion.CountAscending`
  * `FacetSortCriterion.CountDescending`
  * `FacetSortCriterion.AlphabeticalAscending`
  * `FacetSortCriterion.AlphabeticalDescending`

  ```kotlin Kotlin icon=code theme={"system"}
  // Tie-breaking algorithm where refined values are shown first.
  // If refined values are tied, show the facets with the largest counts.
  // If counts are tied, show facets in alphabetical order.
  FacetListPresenterImpl(listOf(IsRefined, CountDescending, AlphabeticalAscending))
  ```
</ParamField>

<ParamField body="limit" type="Int" default={10}>
  The number of facet values to retrieve.

  ```kotlin Kotlin icon=code theme={"system"}
  FacetListPresenterImpl(limit = 5)
  ```
</ParamField>