API Reference / InstantSearch iOS Widgets / SearchBox
Widget signature
QueryInputConnector(
  searcher: SingleIndexSearcher,
  interactor: QueryInputInteractor,
  searchTriggeringMode: SearchTriggeringMode,
  controller: QueryInputController
)

About this widget

Component that performs a text-based query.

Examples

Instantiate a QueryInputConnector.

1
2
3
4
5
6
7
let searcher: SingleIndexSearcher = .init(appID: "YourApplicationID",
                                          apiKey: "YourSearchOnlyAPIKey",
                                          indexName: "YourIndexName")
let searchBarController: SearchBarController = .init(searchBar: UISearchBar())
let queryInputConnector: QueryInputConnector = .init(searcher: searcher,
                                                     searchTriggeringMode: .searchAsYouType,
                                                     controller: searchBarController)

Parameters

searcher
type: Searcher
Required

The Searcher that handles your searches.

interactor
type: QueryInputInteractor
default: .init()
Optional

The logic applied to SearchBox.

searchTriggeringMode
type: SearchTriggeringMode
default: .searchAsYouType
Optional

Defines the event triggering a new search. Can either be .searchAsYouType or .searchOnSubmit.

controller
type: QueryInputController
default: nil
Optional

Controller interfacing with a concrete query input view.

Low-level API

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

  • Searcher: The Searcher that handles your searches.
  • QueryInputInteractor: The logic that handles new search inputs.
  • QueryInputController: The controller interfacing with a concrete input view.
1
2
3
4
5
6
7
8
let searcher: SingleIndexSearcher = .init(appID: "YourApplicationID",
                                          apiKey: "YourSearchOnlyAPIKey",
                                          indexName: "YourIndexName")
let queryInputInteractor: QueryInputInteractor = .init()
let searchBarController: SearchBarController = .init(searchBar: UISearchBar())

queryInputInteractor.connectSearcher(searcher, searchTriggeringMode: .searchAsYouType)
queryInputInteractor.connectController(searchBarController)

Customizing your view

The default controllers, e.g. TextFieldController and 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?