> ## 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.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```kotlin Signature theme={"system"}
FacetListConnector(
searcher: HitsSearcher,
filterState: FilterState,
attribute: String,
selectionMode: SelectionMode,
items: List,
persistentSelection: Boolean,
groupID: FilterGroupID,
)
```
Browse the RefinementList example code on GitHub.
## 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`
selectableFacet = selectableFacet,
onClick = { facet -> facetListState.onSelection?.invoke(facet) }
)
}
}
searcher.searchAsync()
}
override fun onDestroy() {
super.onDestroy()
connections.disconnect()
searcher.cancel()
}
}
```
## Parameters
The [`Searcher`](/doc/api-reference/widgets/instantsearch/android#hitssearcher) that handles your searches.
The [`FilterState`](/doc/api-reference/widgets/filter-state/android) that holds your filters.
The attribute to filter.
Whether the list can have `Single` or `Multiple` selections.
If specified, the default facet values to display.
When true, the selection will be kept even if it does not match current results anymore.
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.
## View
The view that renders the facets.
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)
```
## Presenter
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))
```
The number of facet values to retrieve.
```kotlin Kotlin icon=code theme={"system"}
FacetListPresenterImpl(limit = 5)
```