Refinement List

Shows a list of facets for refining search results.

Signature

FacetListConnector(
  searcher: SingleIndexSearcher,
  filterState: FilterState,
  attribute: Attribute,
  selectionMode: SelectionMode,
  facets: [Facet],
  operator: RefinementOperator,
  groupName: String,
  controller: FacetListController,
  presenter: FacetListPresenter
)

Explore example code

Browse the Refinement List example code on GitHub.

About this widget

RefinementList is a filtering view that displays facets and lets users refine the search results by filtering on specific values.

Requirements

The attribute provided to the widget must be in attributes for faceting, either on the dashboard or using the attributesForFaceting parameter with the API.

Examples

Instantiate a FacetListConnector and launch an initial search on its searcher.

Swift

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

searcher · HitsSearcher · required

The Searcher that handles your searches.

filterState · FilterState · required

The FilterState that holds your filters.

attribute · Attribute · required

The attribute to filter.

selectionMode · SelectionMode · default: .multiple

Whether a user can select .single or .multiple values.

facets · [Facet] · default:

If specified, the default facet value(s) to apply.

operator · 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 for more complex result refinement.

groupName · String · default: The raw value of the `attribute` parameter

Filter group name.

controller · FacetListController · default: nil

Controller interfacing with a concrete facet list view.

presenter · SelectableListPresentable · default: nil

Presenter defining how a facet appears in the controller.

Presenter

sortBy · [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

// 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)]
    )

limit · Int · default: 10

The number of facet values to retrieve.

Swift

facetListPresenter =  .init(limit: 5)

showEmptyFacets · Bool · default: true

Whether to show facets with a facet count of 0.

Swift

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

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

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

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.