> ## 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.

```swift Signature theme={"system"}
FacetListConnector(
  searcher: SingleIndexSearcher,
  filterState: FilterState,
  attribute: Attribute,
  selectionMode: SelectionMode,
  facets: [Facet],
  operator: RefinementOperator,
  groupName: String,
  controller: FacetListController,
  presenter: FacetListPresenter
)
```

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-ios/tree/master/Examples/Showcase">
  Browse the Refinement List 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 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

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

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

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

<ParamField body="selectionMode" type="SelectionMode" post={["default: .multiple"]}>
  Whether a user can select `.single` or `.multiple` values.
</ParamField>

<ParamField body="facets" type="[Facet]" post={["default: "]}>
  If specified, the default facet value(s) to apply.
</ParamField>

<ParamField body="operator" type="RefinementOperator" required>
  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.
</ParamField>

<ParamField body="groupName" type="String" post={["default: The raw value of the `attribute` parameter"]}>
  Filter group name.
</ParamField>

<ParamField body="controller" type="FacetListController" post={["default: nil"]}>
  Controller interfacing with a concrete facet list view.
</ParamField>

<ParamField body="presenter" type="SelectableListPresentable" post={["default: nil"]}>
  Presenter defining how a facet appears in the controller.
</ParamField>

## Presenter

<ParamField body="sortBy" type="[FacetSortCriterion]" default="[.count(order: .descending)]">
  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)]
      )
  ```
</ParamField>

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

  ```swift Swift icon=code theme={"system"}
  facetListPresenter =  .init(limit: 5)
  ```
</ParamField>

<ParamField body="showEmptyFacets" type="Bool" default={true}>
  Whether to show facets with a facet count of 0.

  ```swift Swift icon=code theme={"system"}
  facetListPresenter =  .init(showEmptyFacets: false)
  facetListPresenter =  .init(showEmptyFacets: true)
  ```
</ParamField>

## 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<Facet>])`

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<Facet>] = []
  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<Facet>]) {
    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<Facet> = 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.