API Reference / iOS InstantSearch Widgets / Filter List (Tag)
Apr. 24, 2019

Filter List (Tag)

About this widget

FilterList.Tag is a filtering view that displays any kind of tag filters and lets the user refine the search results by selecting them.

Compared to the RefinementList, which takes its values from the search response facets, this widget displays tag filters that you add yourself.

To add a filter list to your search experience, use these components:

  • Searcher: The Searcher 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.
See code examples

Examples

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

class TagFilterListViewController: UIViewController {
  
  let searcher: SingleIndexSearcher = SingleIndexSearcher(appID: "YourApplicationID",
                                                          apiKey: "YourSearchOnlyAPIKey",
                                                          indexName: "YourIndexName")
  let filterState: FilterState = .init()
  
  let tagFilters: [Filter.Tag] = [
    "coupon",
    "free shipping",
    "free return",
    "on sale",
    "no exchange"
  ]

  lazy var filterListInteractor: TagFilterListInteractor = { .init(items: tagFilters) }()
  
  let filterListController: FilterListTableController<Filter.Tag> = .init(tableView: UITableView())
  
  override func viewDidLoad() {
    super.viewDidLoad()
    setup()
  }
  
  func setup() {
    searcher.connectFilterState(filterState)
    filterListInteractor.connectFilterState(filterState, operator: .or)
    filterListInteractor.connect(to: filterListController)
    searcher.search()
  }

}

Parameters

items
type: [Filter.Tag]
default: []
Required

The tag filters to display.
Copy 
1
2

let items = [Filter.Tag(value: "promo")]
TagFilterListInteractor(items: items)
operator
type: RefinementOperator
Required

Whether we apply an and or or behavior to the filters in the filterState.

For example if we have an or behavior, the filter sent to Algolia will be _tags:promo OR color:green.
Copy 
1

filterListInteractor.connectFilterState(filterState, .or)
selectionMode
type: SelectionMode
default: .multiple
Optional

Whether the list can have Single or Multiple selections.
Copy 
1

TagFilterListInteractor(items: items, selectionMode: .multiple)

Customize your view

The controllers provided by default, like 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 we require a reload of the list view.

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

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)
  }
  
}

Did you find this page helpful?

iOS InstantSearch v5