API Reference / InstantSearch iOS Widgets / SearchBox
Apr. 24, 2019

About this widget

The searchBox is used to perform a text-based query.

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

  • Searcher: The Searcher that handles your searches.
  • QueryInputInteractor: The business logic that handles new search inputs.
  • QueryInputController: The controller interfacing with a concrete input view.

Examples

SearchBar example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
let searchBar = UISearchBar()

let queryInputInteractor: QueryInputInteractor
let searchBarController: SearchBarController
let searcher: SingleIndexSearcher

override init(nibName nibNameOrNil: String?, bundle nibBundleOrNil: Bundle?) {
  searcher = SingleIndexSearcher(...)
  queryInputInteractor = .init()
  searchBarController = .init(searchBar: searchBar)

  super.init(nibName: nibNameOrNil, bundle: nibBundleOrNil)
}

override func viewDidLoad() {
  super.viewDidLoad()
  
  queryInputInteractor.connectSearcher(searcher, searchTriggeringMode: .searchAsYouType)
  queryInputInteractor.connectController(searchBarController)

  searcher.search() // In case we want to do a search when on empty query
}

TextField example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
let textField = UITextField()

let queryInputInteractor: QueryInputInteractor = .init()
let textFieldController: TextFieldController = .init(textField: textField)
let searcher = SingleIndexSearcher(...)

override func viewDidLoad() {
  super.viewDidLoad()
  
  queryInputInteractor.connectSearcher(searcher, searchTriggeringMode: .searchAsYouType)
  queryInputInteractor.connectController(textFieldController)

  searcher.search() // In case we need to do a search when on empty query
}

Parameters

searchTriggeringMode
type: SearchTriggeringMode
default: .searchAsYouType
Optional

Can either be .searchAsYouType or .searchOnSubmit.

1
2
queryInputInteractor.connectSearcher(searcher, searchTriggeringMode: .searchAsYouType)
queryInputInteractor.connectSearcher(searcher, searchTriggeringMode: .searchOnSubmit)

Customize your view

The controllers provided by default, like the TextFieldController or the SearchBarController work well when you want to use native UIKit with their default behavior.

If you want to use another component such as a third-party input view, or you want to introduce some custom behavior to the already provided UIKit components, you can create your own controller conforming to the QueryInputController protocol.

Protocol

var onQueryChanged: ((String?) -> Void)?:

Closure you should call when the query is modified.

var onQuerySubmitted: ((String?) -> Void)?

Closure you should call when the query is submitted.

func setQuery(_ query: String?)

Function called when the query is modified from the outside.

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
27
28
29
30
31
32
33
34
35
36
37
38
public class TextFieldController: NSObject, QueryInputController {
  
  public var onQueryChanged: ((String?) -> Void)?
  public var onQuerySubmitted: ((String?) -> Void)?
  
  let textField: UITextField

  public init (textField: UITextField) {
    self.textField = textField
    super.init()
    setupTextField()
  }
  
  public func setQuery(_ query: String?) {
    textField.text = query
  }

  @objc func textFieldTextChanged(textField: UITextField) {
    guard let searchText = textField.text else { return }
    onQueryChanged?(searchText)
  }
  
  private func setupTextField() {
    textField.returnKeyType = .search
    textField.addTarget(self, action: #selector(textFieldTextChanged), for: .editingChanged)
    textField.delegate = self
  }
  
}

extension TextFieldController: UITextFieldDelegate {
  
  public func textFieldShouldReturn(_ textField: UITextField) -> Bool {
    onQuerySubmitted?(textField.text)
    return true
  }
  
}

Did you find this page helpful?