API Reference / InstantSearch iOS Widgets / Filter Toggle

Filter Toggle

Widget signature
FilterToggleConnector<Filter: FilterType>(
  filterState: FilterState,
  filter: Filter,
  isSelected: Bool,
  refinementOperator: RefinementOperator,
  groupName:  String?,
  controller: FilterSwitchController<FilterType>
)

About this widget

Filter Toggle is a filtering component that displays any kind of filter, and lets the user refine the search results by toggling it on or off.

Examples

Instantiate a FilterToggleConnector and launch an initial search on its Searcher.

1
2
3
4
5
6
7
8
9
10
11
12
13
let searcher: SingleIndexSearcher = .init(appID: "YourApplicationID",
                                          apiKey: "YourSearchOnlyAPIKey",
                                          indexName: "YourIndexName")

let filterState: FilterState = .init()
let filterToggleSwitchController: FilterSwitchController<Filter.Tag> = .init(switch: UISwitch())

let filterToggleConnector = FilterToggleConnector(filterState: filterState,
                                                  filter: "on sale" as Filter.Tag,
                                                  controller: filterToggleSwitchController)

searcher.connectFilterState(filterState)
searcher.search()

Parameters

filterState
type: FilterState
Required

The FilterState that holds your filters.

filter
type: Filter
Required

The Filter to toggle.

interactor
type: SelectableInteractor<Filter>
default: .init()
Required

The logic applied to Filter Toggle.

isSelected
type: Bool
default: false
Required

Whether the filter is initially selected.

refinementOperator
type: RefinementOperator
default: .and
Optional

Whether the filter is added to a conjuncitve(and) or a disjuncitve (or) group in the filter state.

groupName
type: String
default: nil
Optional

Defines the group name in which filter will be placed in FilterState. If not specified, the name of the filter attribute will be used as a group name.

controller
type: CurrentFiltersController
default: nil
Optional

The Controller interfacing with a concrete toggle filter view.

Low-level API

If you want to fully control the Filter Toggle components and connect them manually, use the following components:

1
2
3
4
5
6
7
8
9
10
11
12
let searcher: SingleIndexSearcher = .init(appID: "YourApplicationID",
                                          apiKey: "YourSearchOnlyAPIKey",
                                          indexName: "YourIndexName")
let filterState: FilterState = .init()
let filter: Filter.Tag = "on sale"
let filterToggleSwitchController: FilterSwitchController<Filter.Tag> = .init(switch: UISwitch())
let onSaleFilterInteractor: SelectableInteractor<Filter.Tag> = .init(item: filter)
    
searcher.connectFilterState(filterState)
onSaleFilterInteractor.connectFilterState(filterState)
onSaleFilterInteractor.connectController(filterToggleSwitchController)
searcher.search()

Customizing your view

The default controllers, e.g., FilterSwitchController, work well when you want to use native UIKit with their default behavior.

If you want to use another component such as a UIButton, 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 SelectableController protocol.

Protocol

var onClick: ((Bool) -> Void)?:

Closure to call when a filter is toggled.

func setSelected(_ isSelected: Bool)

Function called when a selection state of filter is updated. This is the UI State of the toggle. Make sure to update your view here when you get the new selection state.

Example

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
public class FilterSwitchController<F: FilterType>: SelectableController {

  public typealias Item = F

  public let `switch`: UISwitch

  public var onClick: ((Bool) -> Void)?

  public init(`switch`: UISwitch) {
    self.switch = `switch`
    `switch`.addTarget(self, action: #selector(didToggleSwitch), for: .valueChanged)
  }

  @objc func didToggleSwitch(_ switch: UISwitch) {
    onClick?(`switch`.isOn)
  }

  public func setSelected(_ isSelected: Bool) {
    self.switch.isOn = isSelected
  }

  public func setItem(_ item: F) {

  }

}

Did you find this page helpful?