Skip to main content
Signature
SearchBoxConnector(
  searcher: AnyObject & Searchable & QuerySettable,
  interactor: SearchBoxInteractor,
  searchTriggeringMode: SearchTriggeringMode,
  controller: SearchBoxController
)
Explore example code

​
About this widget

A component that performs a text-based query.

​
Examples

Instantiate a SearchBoxConnector.
Swift
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
Searcher
required
The Searcher that handles your searches.
​
interactor
SearchBoxInteractor
default: .init()
The logic applied to SearchBox.
​
searchTriggeringMode
SearchTriggeringMode
default: .searchAsYouType
Defines the event triggering a new search.
  • .searchAsYouType. Triggers a search on each keystroke.
  • .searchOnSubmit. Triggers a search on submitting the query.
​
controller
SearchBoxController
default: nil
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.
Swift
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, TextFieldController and SearchBarController, work well with UIKit. If you want to use another component, such as a third-party input view, or introduce custom behaviors to UIKit components, you can create a controller that conforms 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

Swift
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 implements the SearchBoxController protocol for SwiftUI. SearchBoxObservableController must be connected to the SearchBoxConnector or SearchBoxInteractor like any other SearchBoxController implementation.
Swift
struct ContentView: View {

  @ObservedObject var searchBoxObservable: SearchBoxObservableController = .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.
⌘I