API Reference / InstantSearch iOS / SearchBox

SearchBox

Signature 
SearchBoxConnector(
  searcher: AnyObject & Searchable & QuerySettable,
  interactor: SearchBoxInteractor,
  searchTriggeringMode: SearchTriggeringMode,
  controller: SearchBoxController
)
See code examples

About this widget

Component that performs a text-based query.

Examples

Instantiate a SearhBoxConnector.

Copy 
1
2
3
4
5
6
7
8
9

let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")
let searchBarController: SearchBarController = .init(searchBar: UISearchBar())
// If your project targets iOS 13+, you should use TextFieldController(searchBar: UISearchBar()) instead:
// let searchBarController: TextFieldController(searchBar: UISearchBar())
let searchBoxConnector: SearchBoxConnector = .init(searcher: searcher,
                                                   searchTriggeringMode: .searchAsYouType,
                                                  controller: searchBarController)

Parameters

searcher
type: Searcher
Required

The Searcher that handles your searches.
interactor
type: SearchBoxInteractor
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: SearchBoxController
default: nil
Optional

Controller interfacing with a concrete search box 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.
  • SearchBoxInteractor: The logic that handles new search inputs.
  • SearchBoxController: The controller interfacing with a concrete input view.
Copy 
1
2
3
4
5
6
7
8
9

let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")
let searchBoxInteractor: SearchBoxInteractor = .init()
let searchBarController: SearchBarController = .init(searchBar: UISearchBar())
// if your project targets iOS 13+, the usage of TextFieldController(searchBar: UISearchBar()) is recommended

searchBoxInteractor.connectSearcher(searcher, searchTriggeringMode: .searchAsYouType)
searchBoxInteractor.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 SearchBoxController 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.

Implementation 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

public class TextFieldController: NSObject, SearchBoxController {
  
  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
  }
  
}

SwiftUI

InstantSearch provides the SearchBar SwiftUI view which you can embed in your views. It uses SearchBoxObservableController as a data model, which is an implementation of the SearchBoxController protocol adapted for usage with SwiftUI. SearchBoxObservableController must be connected to the SearchBoxConnector or SearchBoxInteractor like any other SearchBoxController implementation.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12

struct ContentView: View {

  @ObservedObject var searchBoxObservable: SearchBixObservableController = .init()
  @State var isEditing = false

  var body: some View {
    SearchBar(text: $searchBoxObservable.query,
          isEditing: $isEditing,
          onSubmit: searchBoxObservable.submit)
  }

}

If you prefer to create a custom SwiftUI view that handles the query input, you can directly use the SearchBoxObservableController as a data model. It provides the query property along with the submit function to streamline the design process of your custom SwiftUI view.

Did you find this page helpful?
InstantSearch iOS v7