> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Refinement List
> 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 ;
};
```swift Signature theme={"system"}
FacetListConnector(
searcher: SingleIndexSearcher,
filterState: FilterState,
attribute: Attribute,
selectionMode: SelectionMode,
facets: [Facet],
operator: RefinementOperator,
groupName: String,
controller: FacetListController,
presenter: FacetListPresenter
)
```
Browse the Refinement List 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 the 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
Instantiate a `FacetListConnector` and launch an initial search on its searcher.
```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
apiKey: "YourSearchOnlyAPIKey",
indexName: "YourIndexName")
let filterState: FilterState = .init()
let categoryTableViewController: UITableViewController = .init()
let categoryListController: FacetListTableController = .init(tableView: categoryTableViewController.tableView)
let facetListPresenter: FacetListPresenter = .init(sortBy: [.count(order: .descending)], limit: 5, showEmptyFacets: false)
let categoryConnector: FacetListConnector = .init(searcher: searcher,
filterState: filterState,
attribute: "category",
selectionMode: .multiple,
facets: [.init(value: "initial facet", count: 10)],
operator: .and,
controller: categoryListController,
presenter: facetListPresenter)
searcher.search()
```
## Parameters
The [`Searcher`](/doc/api-reference/widgets/instantsearch/ios) that handles your searches.
The [`FilterState`](/doc/api-reference/widgets/filter-state/ios) that holds your filters.
The attribute to filter.
Whether a user can select `.single` or `.multiple` values.
If specified, the default facet value(s) to apply.
Whether you apply an `and` or `or` behavior to the facets in the filterState.
For example, if you select `color` as the attribute and an `or` behavior,\
the filter sent to Algolia will be `color:red OR color:green`.
Use [filters or facet filters](/doc/guides/managing-results/refine-results/filtering/in-depth/filters-and-facetfilters) for more complex result refinement.
Filter group name.
Controller interfacing with a concrete facet list view.
Presenter defining how a facet appears in the controller.
## Presenter
How to sort facets. Must be one or more of the following values:
* `.count(order: .descending)`
* `.count(order: .ascending)`
* `.alphabetical(order: .descending)`
* `.alphabetical(order: .ascending)`
* `.isRefined`
```swift Swift 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.
facetListPresenter =
FacetListPresenter(
sortBy: [.isRefined, .count(order: .descending), .alphabetical(order: .ascending)]
)
```
The number of facet values to retrieve.
```swift Swift icon=code theme={"system"}
facetListPresenter = .init(limit: 5)
```
Whether to show facets with a facet count of 0.
```swift Swift icon=code theme={"system"}
facetListPresenter = .init(showEmptyFacets: false)
facetListPresenter = .init(showEmptyFacets: true)
```
## Low-level API
If you want to fully control the `RefinementList` components and connect them manually, you can use the following components:
* `Searcher`. The [`Searcher`](/doc/api-reference/widgets/instantsearch/ios) that handles your searches.
* `FilterState`. The current state of the filters.
* `FacetListInteractor`. The logic applied to the facets.
* `FacetListController`. The controller that interfaces with a concrete facet list view.
* `FacetListPresenter`. Optional. The presenter that controls the sorting and other settings of the facet list view.
```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
apiKey: "YourSearchOnlyAPIKey",
indexName: "YourIndexName")
let filterState: FilterState = .init()
let facetListInteractor: FacetListInteractor = .init(facets: [.init(value: "initial facet", count: 10)], selectionMode: .multiple)
let categoryTableViewController: UITableViewController = .init()
let categoryListController: FacetListTableController = .init(tableView: categoryTableViewController.tableView)
let facetListPresenter: FacetListPresenter = .init(sortBy: [.count(order: .descending)], limit: 5, showEmptyFacets: false)
facetListInteractor.connectSearcher(searcher, with: "category")
facetListInteractor.connectFilterState(filterState, with: "category", operator: .or)
facetListInteractor.connectController(categoryListController)
facetListInteractor.connectController(categoryListController, with: facetListPresenter)
searcher.connectFilterState(filterState)
searcher.search()
```
## Customizing your view
The controllers provided by default,
like the `FacetListTableViewController` work well when you want to use native UIKit with their default behavior.
If you want to use another component such as a `UICollectionView`,
a third-party input view, or you want to introduce some custom behavior to the already provided UIKit component,
you can create your own controller conforming to the `FacetListController` protocol.
### Protocol
`var onClick: ((Facet) -> Void)?`:
Closure to call when a new facet is clicked.
`func setSelectableItems(selectableItems: [SelectableItem])`
Function called when a new array of selectable facets is updated. This is the UI State of the refinement list.
`func reload()`
Function called when you want ti reload the list view.
### Implementation example
```swift Swift icon=code theme={"system"}
open class FacetListTableViewController: NSObject, FacetListController {
public var onClick: ((Facet) -> Void)?
public var tableView: UITableView
var selectableItems: [SelectableItem] = []
var cellID: String
public init(tableView: UITableView, cellID: String = "FacetList") {
self.tableView = tableView
self.cellID = cellID
super.init()
tableView.register(UITableViewCell.self, forCellReuseIdentifier: cellID)
tableView.dataSource = self
tableView.delegate = self
}
public func setSelectableItems(selectableItems: [SelectableItem]) {
self.selectableItems = selectableItems
}
public func reload() {
tableView.reloadData()
}
}
extension FacetListTableViewController: UITableViewDataSource {
open func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
return selectableItems.count
}
open func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
let cell = tableView.dequeueReusableCell(withIdentifier: cellID, for: indexPath)
let selectableRefinement: SelectableItem = selectableItems[indexPath.row]
let facetAttributedString = NSMutableAttributedString(string: selectableRefinement.item.value)
let facetCountStringColor = [NSAttributedString.Key.foregroundColor: UIColor.gray, .font: UIFont.systemFont(ofSize: 14)]
let facetCountString = NSAttributedString(string: " (\(selectableRefinement.item.count))", attributes: facetCountStringColor)
facetAttributedString.append(facetCountString)
cell.textLabel?.attributedText = facetAttributedString
cell.accessoryType = selectableRefinement.isSelected ? .checkmark : .none
return cell
}
}
extension FacetListTableViewController: UITableViewDelegate {
open func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
let selectableItem = selectableItems[indexPath.row]
self.onClick?(selectableItem.item)
}
}
```
### SwiftUI
InstantSearch provides the `FacetList` SwiftUI view which you can embed in your views.
It uses `FacetListObservableController` as a data model,
which is an implementation of the `FacetListController` protocol adapted for usage with SwiftUI.
`FacetListObservableController` must be connected to the `FacetListConnector` or `FacetListInteractor`,
like any other `FacetListController` implementation.
You can define the appearance of the view representing a single facet and its selection state
or use the `FacetRow` view provided by InstantSearch.
```swift Swift icon=code theme={"system"}
struct ContentView: View {
@ObservedObject var facetListController: FacetListObservableController
var body: some View {
FacetList(facetListController) { facet, isSelected in
// Use the implementation provided by InstantSearch
// FacetRow(facet: facet,
isSelected: isSelected)
// Or declare a custom single facet view
HStack {
Text(facet.value)
Spacer()
if isSelected {
Image(systemName: "checkmark")
.foregroundColor(.accentColor)
}
}
.contentShape(Rectangle())
.frame(idealHeight: 44)
.padding(.horizontal, 5)
}
}
}
```
If you prefer to create a custom SwiftUI view that presents the list of facets,
you can directly use the `FacetListObservableController` as a data model.
It provides `facets` and `selections` properties along with convenient `toggle` and `isSelected` functions to streamline the design process of your custom SwiftUI view.