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

About this widget

The SearchBox widget is used to let the user perform a text-based query. It is the main component of a search experience.

There are three ways to use a SearchBox in your app with InstantSearch:

  • The SearchBarWidget, which is a specialized UISearchBar. Since it inherits from UISearchBar it supports all of its existing attributes.
  • The TextFieldWidget which is a specialized UITextField. Also, it supports all the UITextField existing attributes.
  • Using InstantSearch.register(searchController:) for a UISearchController or InstantSearch.register(searchBar:) for a UISearchBar for InstantSearch to subscribe to typing events and automatically send search events to Algolia on each new keystroke.

As with any UIView, you can specify the first two widgets in two ways:

  • Interface builder, by drag and dropping a Search Bar from the Object library, and then specifying SearchBarWidget as its Custom class inside the Identity Inspector.
  • Programatically, by initializing the widget, then using view.addSubview(widget).

Examples

1
2
3
4
var searchBox = SearchBarWidget(frame: CGRect)
// var searchBox = TextFieldWidget(frame: CGRect)
searchBox.index = "clothes"
self.view.addSubview(searchBox)

Parameters

index
type: string
default:
Optional

The index name if you want the searchBox to search only in a single index. When empty, the searchBox searches through all registered indices.

1
searchBox.index = "myIndex"
variant
type: string
default:
Optional

Allows to distinguish between two widgets that target the same index, but with different search parameters. Specify an index variant name for the searchBox to search only through a single index variant.

1
searchBox.variant = "myVariant"

SearchViewModel

Widgets work well when you want default styles to be applied and don’t need heavy customization regarding its behavior.

ViewModels are useful when you need full control over the rendering without having to reimplement any business logic. As soon as you hit a feature wall using the default widgets, you can use ViewModels to have more flexibility and control over the delegate and datasource methods.

ViewModels encapsulate the logic for a specific search concept and provide a way to interact with InstantSearch. You can use them to customize your search box.

Methods

  • search(query:)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@IBOutlet weak var searchBar: SearchBarWidget!
var searchViewModel: SearchViewModel!

override func viewDidLoad() {
        super.viewDidLoad()

        searchViewModel = SearchViewModel(view: searchBar)
        InstantSearch.shared.register(viewModel: searchViewModel)

        // Now can access access the searchBar's delegate
        searchBar.delegate = self
    }

    public func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) {
        // Call the search function of the viewModel. It takes care of changing the
        // search state and sending search events when new results arrive.
        searchViewModel.search(query: searchText)
    }

Did you find this page helpful?