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

# Filter List (Tag)

> Shows a list of tag filters for refining search results.

export const Facet = () => <Tooltip tip="An attribute in your records that lets users filter or group results (for example, by color, brand, or price)." cta="Faceting" href="/doc/guides/managing-results/refine-results/faceting">
    facet
  </Tooltip>;

<div className="not-prose algolia-flavor-switcher">
  <div className="afs-dropdown">
    <div className="afs-trigger" role="button" tabIndex="0" aria-haspopup="listbox">
      <span className="afs-current">iOS</span>

      <svg className="afs-chevron lucide lucide-chevron-down" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <path d="m6 9 6 6 6-6" />
      </svg>
    </div>

    <ul className="afs-menu" role="listbox">
      <li role="option" aria-selected="true"><a className="afs-option is-current" href="/doc/api-reference/widgets/filter-list-tag/ios"><span className="afs-option-name">iOS</span><span className="afs-option-lib">InstantSearch iOS</span></a></li>
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/filter-list-tag/android"><span className="afs-option-name">Android</span><span className="afs-option-lib">InstantSearch Android</span></a></li>
    </ul>
  </div>
</div>

```swift Signature theme={"system"}
TagFilterListConnector(
  tagFilters: [TagFilter],
  selectionMode: SelectionMode,
  filterState: FilterState,
  operator: RefinementOperator,
  groupName: String,
  controller: FilterListTableController<Filter.Tag>
)
```

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-ios/tree/master/Examples/Showcase">
  Browse the Filter List (Tag) example code on GitHub.
</Card>

## About this widget

`TagFilterList` is a filtering component that displays [tag filters](/doc/api-reference/api-parameters/tagFilters)
and lets users refine the search results by selecting them.

Compared to the [`RefinementList`](/doc/api-reference/widgets/refinement-list/ios),
which takes its values from the search response <Facet />,
this widget displays tag filters that you add yourself.

## Examples

Instantiate a `TagFilterListConnector` and launch an initial search on its [`Searcher`](/doc/api-reference/widgets/instantsearch/ios).

```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")

let filterState = FilterState()

let filters: [Filter.Tag] = [
  "coupon",
  "free shipping",
  "free return",
  "on sale",
  "no exchange"
]
let filterListTableView: UITableView = .init()
let filterListController: FilterListTableController<Filter.Tag> = .init(tableView: filterListTableView)

let filterListConnector = TagFilterListConnector(tagFilters: filters,
                                                 selectionMode: .multiple,
                                                 filterState: filterState,
                                                 operator: .and,
                                                 groupName: "Tag Filters",
                                                 controller: filterListController)

searcher.connectFilterState(filterState)
searcher.search()
```

## Parameters

<ParamField body="tagFilters" type="[TagFilter]" post={["default: []"]} required>
  The tag filters to display.
</ParamField>

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

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

<ParamField body="operator" type="RefinementOperator" required>
  Whether to apply an `and` or `or` behavior to the filters in the filter state.

  For example with `or`, the filter sent to Algolia is `_tags:promo OR color:green`.
</ParamField>

<ParamField body="groupName" type="String" required>
  Filter group name.
</ParamField>

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

## Low-level API

If you want to fully control the `TagFilterList` 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.
* `TagFilterListInteractor`. The logic applied to the tag filters.
* `FilterListController`. The view that will render the tag filters.

```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")

let filterState = FilterState()

let filters: [Filter.Tag] = [
  "coupon",
  "free shipping",
  "free return",
  "on sale",
  "no exchange"
]
let filterListTableView: UITableView = .init()
let filterListController: FilterListTableController<Filter.Tag> = .init(tableView: filterListTableView)

let filterListInteractor = TagFilterListInteractor(items: filters,
                                                  selectionMode: .multiple)

filterListInteractor.connectFilterState(filterState, operator: .and, groupName: "Tag Filters")
filterListInteractor.connectController(filterListController)

searcher.connectFilterState(filterState)
searcher.search()
```

## Customizing your view

The default controllers, such as the `FilterListTableController`, 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 `TagFilterListController` protocol.

### Protocol

`var onClick: ((Filter.Tag) -> Void)?`:

Closure to call when a filter is clicked.

`func setSelectableItems(selectableItems: [SelectableItem<Filter.Tag>])`

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 the list view requires a reload.

### Implementation example

```swift Swift icon=code theme={"system"}
class TagFilterListTableController: NSObject, TagFilterListController, UITableViewDataSource, UITableViewDelegate {

  public var onClick: ((Filter.Tag) -> Void)?

  public let tableView: UITableView

  public var selectableItems: [SelectableItem<Filter.Tag>] = []
  public var filterPresenter: FilterPresenter?

  let cellID: String

  public init(tableView: UITableView, cellID: String = "cellID") {
    self.tableView = tableView
    self.cellID = cellID
    super.init()
    tableView.dataSource = self
    tableView.delegate = self
    tableView.register(UITableViewCell.self, forCellReuseIdentifier: cellID)
  }

  // MARK: - FilterListController

  public func setSelectableItems(selectableItems: [SelectableItem<Filter.Tag>]) {
    self.selectableItems = selectableItems
  }

  public func reload() {
    tableView.reloadData()
  }

  // MARK: - UITableViewDataSource

  func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return selectableItems.count
  }

  func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: cellID, for: indexPath)
    let filter = selectableItems[indexPath.row]
    let filterPresenter = self.filterPresenter ?? DefaultPresenter.Filter.present
    cell.textLabel?.text = filterPresenter(Filter(filter.item))
    cell.accessoryType = filter.isSelected ? .checkmark : .none

    return cell
  }

  // MARK: - UITableViewDelegate

  func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    let selectableItem = selectableItems[indexPath.row]
    onClick?(selectableItem.item)
  }

}
```

### SwiftUI

InstantSearch provides the `FilterList` SwiftUI view which you can embed in your views.
It uses `FilterListObservableController` as a data model, which is an implementation of the `SelectableListController` protocol adapted for usage with SwiftUI.
`FilterListObservableController` must be connected to the `TagFilterListConnector` or `TagFilterListInteractor` like any other `SelectableListController` implementation.
You have to define the appearance of the view representing a single tag filter and its selection state.

```swift Swift icon=code theme={"system"}
struct ContentView: View {

  @ObservedObject var filterListController: FilterListObservableController<Filter.Tag>

  var body: some View {
    FilterList(filterListController) { filter, isSelected in
      // declare the view presenting a single tag filter and its selection state
      HStack {
        Text(filter.value.description)
        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 tag filters, you can directly use the `FilterListObservableController<Filter.Tag>` as a data model.
It provides `filters` and `selections` properties along with `toggle` and `isSelected` functions to streamline the design process of your custom SwiftUI view.