Get started programmatically

This guide will walk you through the few steps needed to start a project with InstantSearch iOS. Start from an empty iOS project, and create a full search experience from scratch. This search experience will include:

A list to display search results
A search box to type your query
Statistics about the current search
A facet list for filtering results

Installation

To use InstantSearch iOS, you need an Algolia account. You can create a new account, or use the following credentials:

APP ID: latency
Search API Key: 1f6fd3a6fb973cb08419fe7d288fa4db
Index name: bestbuy

These credentials give access to a pre-loaded dataset of products appropriate for this guide.

Create a new project

In Xcode, create a new Project:

On the Template screen, select Single View Application and click next
Specify your Product name, select Swift as the language and iPhone as the device, and then create.

Prepare your storyboard

After generation, the project directly shows the main view controller. Embed this into the Navigation Controller.

Open Main.storyboard
Select ViewController in the View Controller scene
Editor > Embed in > Navigation Controller

Add InstantSearch dependency

To add the InstantSearch package dependency to your Xcode project, you need a dependency manager. This can be the Swift Package Manager, or CocoaPods.

Swift Package Manager

Select File > Swift Packages > Add Package Dependency and enter this repository URL: https://github.com/algolia/instantsearch-ios
You can also navigate to your target’s General pane, and in the Frameworks, Libraries, and Embedded Content section, click the + button, select Add Other, and choose Add Package Dependency.
In the package products selection dialog, select both the InstantSearch and InstantSearchCore dependencies.

CocoaPods

If you don’t have CocoaPods installed on your machine, open your terminal and run sudo gem install cocoapods.
In your terminal, navigate to the root directory of your project and run the pod init command. This command generates a Podfile for you.
Open your Podfile and add pod 'InstantSearch', '~> 7' below your target.
In your terminal, run pod update.
Close your Xcode project. In your terminal, at the root of your project, execute the open projectName.xcworkspace command (replacing projectName with the actual name of your project).

Implementation

Xcode automatically generates a ViewController.swift file when you create a Single View Application. Open this file, and add the following import statement at the top.

Swift

import InstantSearch

Define your record structure

Define a structure that represent a record in your index. For simplicity’s sake, this structure only provides the name of the product. The structure must conform to the Codable protocol to work properly with InstantSearch. Add the following structure definition to the ViewController.swift file:

Swift

struct Item: Codable {
  let name: String
}

Declare hits view controller

In this tutorial search results view controller is represented by a UITableViewController which conforms to HitsController protocol. The following example binds the name of the fetched item to the cell’s textLabel s text property.

Swift

class SearchResultsViewController: UITableViewController, HitsController {

  var hitsSource: HitsInteractor<Item>?

  override func viewDidLoad() {
    super.viewDidLoad()
    tableView.register(UITableViewCell.self, forCellReuseIdentifier: "cell")
  }

  override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    hitsSource?.numberOfHits() ?? 0
  }

  override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: "cell", for: indexPath)
    cell.textLabel?.text = hitsSource?.hit(atIndex: indexPath.row)?.name
    return cell
  }

  override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    if let _ = hitsSource?.hit(atIndex: indexPath.row) {
      // Handle hit selection
    }
  }

}

Refer to the HitsController documentation for more on integrating and customizing the `Hits’ widget.

Complete the view controller

To complete the main view controller of your application, declare a UISearchController. This is a UIKit component that manages the display of search results based on interactions with a search box. It provides a search box, and only requires a search results controller as a parameter. Add a hitsViewController field to the view controller, with the type declared in the previous step. It should be set as an initializer parameter of the search controller.

Swift

class ViewController: UIViewController {

  lazy var searchController = UISearchController(searchResultsController: hitsViewController)
  let hitsViewController = SearchResultsViewController()

}

Initialize your searcher

With the necessary view controllers in place, it’s time to add the search logic. The central part of the search experience is the Searcher. The Searcher performs search requests and obtains search results. Most InstantSearch components are connected with the Searcher. Since only one index is targeted, instantiate a HitsSearcher as the searcher using the proper credentials. Then, add a searchConnector property to the view controller. The purpose of Connectors in InstantSearch is to establish links between its components. Initialize the SearchConnector with the Searcher, search controller, hits interactor and hits view controller as parameters. Finally, activate the search connector by calling its connect() method and then add searcher.search() to launch the first empty search request in the viewDidLoad method.

Swift

class ViewController: UIViewController {

  lazy var searchController = UISearchController(searchResultsController: hitsViewController)
  let hitsViewController = SearchResultsViewController()

  let searcher = HitsSearcher(appID: "latency",
                              apiKey: "1f6fd3a6fb973cb08419fe7d288fa4db",
                              indexName: "bestbuy")
  lazy var searchConnector = SearchConnector<Item>(searcher: searcher,
                                                    searchController: searchController,
                                                    hitsInteractor: .init(),
                                                    hitsController: hitsViewController)

  override func viewDidLoad() {
    super.viewDidLoad()
    searchConnector.connect()
    searcher.search()
  }

}

While fully functional, the search logic isn’t ready to use yet because the search isn’t displayed. Add a setupUI method to the view controller and call it from the viewDidLoad method. Finally, override the viewDidAppear method, and set search controller so that the search controller presents results immediately after the view controller appearance.

Swift

class ViewController: UIViewController {

  lazy var searchController = UISearchController(searchResultsController: hitsViewController)
  let hitsViewController = SearchResultsViewController()

  let searcher = HitsSearcher(appID: "latency",
                              apiKey: "1f6fd3a6fb973cb08419fe7d288fa4db",
                              indexName: "bestbuy")
  lazy var searchConnector = SearchConnector<Item>(searcher: searcher,
                                                    searchController: searchController,
                                                    hitsInteractor: .init(),
                                                    hitsController: hitsViewController)

  override func viewDidLoad() {
    super.viewDidLoad()
    searchConnector.connect()
    searcher.search()
    setupUI()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    searchController.isActive = true
  }

  func setupUI() {
    view.backgroundColor = .white
    navigationItem.searchController = searchController
    searchController.hidesNavigationBarDuringPresentation = false
    searchController.showsSearchResultsController = true
    searchController.automaticallyShowsCancelButton = false
  }

}

You can now build and run your application to see the basic search experience in action. You should see that the results are changing on each key stroke.

Adding statistics

To make the search experience more user-friendly, it would be appropriate to provide an additional feedback about the search results. This is an opportunity to extend the search experience with different InstantSearch modules. First, add a statistics component. This component will show the hit count. This gives users a complete understanding of their search, without the need for extra interaction. Then, instantiate a StatsInteractor, which extracts the required metadata from the search response, and provides an interface to present it to users.

Swift

class ViewController: UIViewController {

  lazy var searchController = UISearchController(searchResultsController: hitsViewController)
  let hitsViewController = SearchResultsViewController()

  let searcher = HitsSearcher(appID: "latency",
                              apiKey: "1f6fd3a6fb973cb08419fe7d288fa4db",
                              indexName: "bestbuy")
  lazy var searchConnector = SearchConnector<Item>(searcher: searcher,
                                                    searchController: searchController,
                                                    hitsInteractor: .init(),
                                                    hitsController: hitsViewController)
  let statsInteractor = StatsInteractor()

  override func viewDidLoad() {
    super.viewDidLoad()
    searchConnector.connect()
    statsInteractor.connectSearcher(searcher)
    searcher.search()
    setupUI()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    searchController.isActive = true
  }

  func setupUI() {
    view.backgroundColor = .white
    navigationItem.searchController = searchController
    searchController.hidesNavigationBarDuringPresentation = false
    searchController.showsSearchResultsController = true
    searchController.automaticallyShowsCancelButton = false
  }

}

The StatsInteractor receives the search statistics now, but it isn’t displayed anywhere yet. To keep the example simple, the hits count will be presented as the title of the view controller. This is probably not the best place to show this in the application interface, but this prevents putting to much layout-related code in this guide. The StatsInteractor presents its data in a component that implements the StatsTextController protocol. Make the view controller conform to this protocol by adding an extension. Now, the view controller can be connected to the StatsInteractor with the corresponding method. Add this connection in the viewDidLoad method.

Swift

class ViewController: UIViewController {

  lazy var searchController = UISearchController(searchResultsController: hitsTableViewController)
  let hitsTableViewController = SearchResultsViewController()

  let searcher = HitsSearcher(appID: "latency",
                              apiKey: "1f6fd3a6fb973cb08419fe7d288fa4db",
                              indexName: "bestbuy")
  lazy var searchConnector = SearchConnector<Item>(searcher: searcher,
                                                    searchController: searchController,
                                                    hitsInteractor: .init(),
                                                    hitsController: hitsTableViewController)
  let statsInteractor = StatsInteractor()

  override func viewDidLoad() {
    super.viewDidLoad()
    searchConnector.connect()
    statsInteractor.connectSearcher(searcher)
    statsInteractor.connectController(self)
    searcher.search()
    setupUI()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    searchController.isActive = true
  }

  func setupUI() {
    view.backgroundColor = .white
    navigationItem.searchController = searchController
    searchController.hidesNavigationBarDuringPresentation = false
    searchController.showsSearchResultsController = true
    searchController.automaticallyShowsCancelButton = false
  }

}

extension ViewController: StatsTextController {

  func setItem(_ item: String?) {
    title = item
  }

}

Build and run your application: you should now see updated results and an updated hit count on each keystroke.

Now you have a better understanding of the organization of InstantSearch modules:

Each module has an Interactor, containing the module’s business-logic.
Each Interactor has a corresponding Controller protocol, which defines the interaction with a UI component.

Out of the box, InstantSearch provides a few basic implementations of the Controller protocol for UIKit components. Examples of these are HitsTableViewController, TextFieldController, and ActivityIndicatorController. Feel free to use them to discover the abilities of InstantSearch with minimal effort. In your own project, you might want implement more custom UI and behavior. If so, it’s up to you to create an implementations of the Controller protocol, and to connect them to a corresponding Interactor.

Filter your results: RefinementList

With your app, you can search more than 10,000 products. However, you don’t want to scroll to the bottom of the list to find the exact product you’re looking for. To resolve it, build a filter that allows to filter products by their category using the RefinementList components. First, add a FilterState component. This component provides a convenient way to manage the state of your filters. In this example, a refinement attribute: category will be added. Finally, add the RefinementList components to other components in the search experience, such as FacetListConnector, FacetListTableController and UITableViewController. The UITableViewController will actually present a facet list. As a result, the definition of your ViewController has to look like this:

Swift

class ViewController: UIViewController {

  lazy var searchController = UISearchController(searchResultsController: hitsViewController)
  let hitsViewController = SearchResultsViewController()

  let searcher = HitsSearcher(appID: "latency",
                              apiKey: "1f6fd3a6fb973cb08419fe7d288fa4db",
                              indexName: "bestbuy")
  lazy var searchConnector = SearchConnector<Item>(searcher: searcher,
                                                    searchController: searchController,
                                                    hitsInteractor: .init(),
                                                    hitsController: hitsViewController,
                                                    filterState: filterState)
  let statsInteractor = StatsInteractor()
  let filterState = FilterState()
  lazy var categoryConnector = FacetListConnector(searcher: searcher,
                                                  filterState: filterState,
                                                  attribute: "category",
                                                  operator: .and,
                                                  controller: categoryListController)

  lazy var categoryListController = FacetListTableController(tableView: categoryTableViewController.tableView)
  let categoryTableViewController = UITableViewController()

  override func viewDidLoad() {
    super.viewDidLoad()
    searchConnector.connect()
    categoryConnector.connect()
    statsInteractor.connectSearcher(searcher)
    statsInteractor.connectController(self)
    searcher.search()
    setupUI()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    searchController.isActive = true
  }

  func setupUI() {
    view.backgroundColor = .white
    navigationItem.searchController = searchController
    searchController.hidesNavigationBarDuringPresentation = false
    searchController.showsSearchResultsController = true
    searchController.automaticallyShowsCancelButton = false
  }

}

extension ViewController: StatsTextController {

  func setItem(_ item: String?) {
    title = item
  }

}

Finally, in the setupUI() method, set up a navigation bar button item that triggers the presentation of the facet list, and sets the title of this list. Add showFilters and dismissFilters functions responsible for the presentation and dismiss logic of the facet list.

Swift

class ViewController: UIViewController {

  lazy var searchController = UISearchController(searchResultsController: hitsViewController)
  let hitsViewController = SearchResultsViewController()

  let searcher = HitsSearcher(appID: "latency",
                              apiKey: "1f6fd3a6fb973cb08419fe7d288fa4db",
                              indexName: "bestbuy")
  lazy var searchConnector = SearchConnector<Item>(searcher: searcher,
                                                    searchController: searchController,
                                                    hitsInteractor: .init(),
                                                    hitsController: hitsViewController,
                                                    filterState: filterState)
  let statsInteractor = StatsInteractor()
  let filterState = FilterState()
  lazy var categoryConnector = FacetListConnector(searcher: searcher,
                                                  filterState: filterState,
                                                  attribute: "category",
                                                  operator: .and,
                                                  controller: categoryListController)

  lazy var categoryListController = FacetListTableController(tableView: categoryTableViewController.tableView)
  let categoryTableViewController = UITableViewController()

  override func viewDidLoad() {
    super.viewDidLoad()
    searchConnector.connect()
    categoryConnector.connect()
    statsInteractor.connectSearcher(searcher)
    statsInteractor.connectController(self)
    searcher.search()
    setupUI()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    searchController.isActive = true
  }

  func setupUI() {
    view.backgroundColor = .white
    navigationItem.searchController = searchController
    navigationItem.rightBarButtonItem = .init(title: "Category", style: .plain, target: self, action: #selector(showFilters))
    searchController.hidesNavigationBarDuringPresentation = false
    searchController.showsSearchResultsController = true
    searchController.automaticallyShowsCancelButton = false
    categoryTableViewController.title = "Category"
  }

  @objc func showFilters() {
    let navigationController = UINavigationController(rootViewController: categoryTableViewController)
    categoryTableViewController.navigationItem.rightBarButtonItem = UIBarButtonItem(barButtonSystemItem: .done, target: self, action: #selector(dismissFilters))
    present(navigationController, animated: true, completion: .none)
  }

  @objc func dismissFilters() {
    categoryTableViewController.navigationController?.dismiss(animated: true, completion: .none)
  }

}

extension ViewController: StatsTextController {

  func setItem(_ item: String?) {
    title = item
  }

}

You can now build and run your application to see your RefinementList in action.

Going further

Your users can enter a query, and your application shows them results as they type. It also provides a possibility to filter the results even further using RefinementList. That is pretty nice already, but you can go further and improve on that.

You can have a look at the examples to see more complex examples of applications built with InstantSearch.
You can head to the components page to see other components that you could use.

Guides

​Installation

​Create a new project

​Prepare your storyboard

​Add InstantSearch dependency

​Swift Package Manager

​CocoaPods

​Implementation

​Define your record structure

​Declare hits view controller

​Complete the view controller

​Initialize your searcher

​Adding statistics

​Filter your results: RefinementList

​Going further

Installation

Create a new project

Prepare your storyboard

Add InstantSearch dependency

Swift Package Manager

CocoaPods

Implementation

Define your record structure

Declare hits view controller

Complete the view controller

Initialize your searcher

Adding statistics

Filter your results: RefinementList

Going further