InstantSearch iOS: a SwiftUI and UIKit layer over Algolia

Four products, and the boundary between them is the design decision

The most useful thing about this repository is that it is not one library. It is four, and picking between them is the first decision an adopting team has to make. InstantSearch Insights is a library for capturing search-related events. InstantSearch Core holds the business logic modules of InstantSearch. InstantSearch is the complete toolset including the UIKit components. InstantSearch SwiftUI is the set of SwiftUI data models and views that sit on top of Core.

That split maps onto real project boundaries. A team with an existing UI layer but no search can take Core and write its own views. A team that wants the standard UIKit widgets takes the full InstantSearch product. A team running SwiftUI takes the SwiftUI models and views. Insights is orthogonal to all of it, since it records events rather than rendering results.

Underneath sits Algolia's Swift API Client v9, which does the actual API traffic. InstantSearch iOS is a layer of components and helpers above that client, so nothing here removes the requirement to have a populated Algolia index.

The searcher, the connector and the interactor do the wiring

The API surface in the project's usage example is small and explicit. A HitsSearcher is created with an appID, an apiKey and an indexName, and it is the object that performs the query. A SearchConnector then takes that searcher plus a searchController, a hitsInteractor and a hitsController and wires them together. The connector exposes connect(), and the searcher exposes search().

The view side conforms to HitsController and reads from a HitsInteractor held as hitsSource, which means the number of rows and the cell contents both come from the interactor rather than from a local array the view owns. A Hit at a given index is fetched with hit(atIndex:).

The value of this arrangement is that the view never issues a request. Adding a refinement, changing the query or paginating happens inside the connector and the interactor, and the table view simply re-reads the same source. The cost is a layer of indirection that has to be understood before a single row appears, and the hit type is a generic parameter, so Item has to conform to Codable as the example shows.

Installing through Swift Package Manager, or CocoaPods when the podspec fits

Two installation paths are documented, and they expose different things. With Swift Package Manager, the project's instructions are to open Xcode 11 or later and use File, Swift Packages, Add Package Dependency with the InstantSearch repo URL, then select the products you want from the provided list. Framework authors who depend on InstantSearch edit Package.swift instead.

let package = Package(
    // 8.0.0 ..< 9.0.0
    dependencies: [
        .package(url: "https://github.com/algolia/instantsearch-ios", from: "8.0.0")
    ],
    // ...
)

The CocoaPods route adds one line to a Podfile, and the commented alternatives show the subspec split in full.

pod 'InstantSearch', '~> 8.0'
# pod 'InstantSearch/Insights' for access to Insights library only
# pod 'InstantSearch/Core' for access business logic without UIKit components
# pod 'InstantSearch/SwiftUI' for access to SwiftUI components

After editing the Podfile, the command to run is pod update, which resolves the new dependency.

$ pod update

A first UIKit search screen in four wiring steps

The example in the project shows the smallest useful shape. A Codable item type is declared, the results view controller adopts HitsController and reads from a HitsInteractor, and a plain table view cell is registered for the cell reuse identifier "cell".

import InstantSearch

struct Item: Codable {
  let name: String
}

class SearchResultsViewController: UITableViewController, HitsController {
  var hitsSource: HitsInteractor<Item>?
  override func viewDidLoad() {
    super.viewDidLoad()
    tableView.register(UITableViewCell.self, forCellReuseIdentifier: "cell")
  }

The controller that owns the search then creates the searcher and the connector. Note that the searcher is constructed with try!, so a failure to build it traps.

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

In viewDidLoad the sequence is searchConnector.connect(), then searcher.search(), then setupUI(). The expected visible result, according to the project, is that results change on each key stroke.

Insights is an event recorder, not part of the results path

The Insights product deserves to be read separately from the rest, because it changes what your project collects rather than what it renders. It is described as a library that allows developers to capture search-related events, and it is a distinct pod, a distinct SwiftPM product and a separate module that can be taken on its own without any UIKit code.

That distinction matters for two reasons. First, it is an analytics surface, so what you send becomes part of your data collection footprint, and that deserves a deliberate decision rather than arriving as a side effect of installing the main product. Second, the Examples directory contains an Insights example alongside examples for QuerySuggestions, CategoriesHits, MultiIndex, VoiceSearch, WatchSearch and TVSearch, which shows the feature set the library is expected to cover across UIKit, SwiftUI and platform extensions.

The repository also exposes the testing side. A .env.sample file at the root defines ALGOLIA_APPLICATION_ID_1 and ALGOLIA_ADMIN_KEY_1 as the credentials used in tests, so those two names are what a contributor fills in locally before running the suite.

The layer stops at the screen and expects Algolia behind it

There are several places where this library is the wrong tool, and they all follow from the same design choice. It renders a search interface and issues queries through the Swift API Client v9 to Algolia. It is not a search engine, it has no index of its own, and nothing in the project's documentation describes an offline or local index. If your records live in Postgres, Mongo or a plain file server, the results still have to arrive through Algolia before this UI has anything to show.

The example code also shows where the rough edges are. The searcher is built with try!, which turns a configuration mistake into a crash instead of an error you can handle. The credentials in the snippet are shared demo values for a public index, so a real app must not ship them.

On the compatibility side, the badges state SwiftPM and Mac Catalyst compatibility, and the project notes that since Swift 5 and Xcode 11 the Swift Package Manager works with the iOS, macOS and tvOS build systems. If your app targets a platform outside that set, the package manager path described here does not cover it, and the repository's platform matrix should be checked against your own target list before you commit to it.

Using the Swift API Client v9 directly instead

The alternative approach is to skip InstantSearch iOS and talk to the Algolia Swift API Client v9 yourself. That library is what InstantSearch iOS is built on, so the network and query layer is identical either way. The difference sits entirely above it.

With the client alone you get requests and responses and nothing else. You own the debouncing of keystrokes, the caching of previous results, the paging state, the binding from a query to a list view, and the event tracking. With InstantSearch iOS those are the parts the connectors and interactors handle for you, and the UIKit and SwiftUI products supply views that are already written against that machinery.

The trade-off is explicit. InstantSearch iOS is worth its dependency when you want the standard search experience and would otherwise rebuild it, and it is a poor trade when your interface needs a layout the provided components do not model, because then you are keeping the interactor layer but replacing the view layer anyway. A team that only needs to run a query and show a list of names may find the client and a handful of lines of Swift the smaller commitment.

Editorial conclusion

InstantSearch iOS fits teams already serving an Algolia index who want a typed, reactive search screen in UIKit or SwiftUI rather than hand written HTTP calls and debounce logic. It is the wrong choice if your data lives elsewhere, if you need offline search, or if you only want a single text field. Check first that the four product boundaries match how your team splits modules, that the CocoaPods subspec or SwiftPM product you pick matches the UI framework you use, and that the release you pin still matches the Swift API Client v9 the layer expects.

Frequently asked questions

Official sources

1. algolia/instantsearch-ios on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases