Hits

Shows a list of search results.

Signature

HitsConnector<Hit: Codable>(
  appID: ApplicationID,
  apiKey: APIKey,
  indexName: IndexName,
  infiniteScrolling: InfiniteScrolling,
  showItemsOnEmptyQuery: Bool,
  filterState: FilterState,
  controller: HitsController
)

Explore example code

About this widget

Use the Hits component to display a list of search results. The component automatically reloads results when new hits are fetched from Algolia.

HitsConnector is a generic class you can customize by implementing a class or structure that represents your record and conforms to the Codable protocol. If, for some reason, the engine can’t parse a record into the type you provided, the onError event of the Interactor instance will be triggered.

If you prefer to deal with raw JSON objects, set JSON as the type of record and use the rawHitAtIndex(_ row: Int) -> [String: Any]? method to access a hit.

See also:

• Multi-index search
• Searches without results

Examples

Define the custom type representing the hits in your index conforming to Codable protocol.

Swift

struct CustomHitModel: Codable {
  let name: String
}

Instantiate a HitsConnector and launch an initial search on its searcher.

Swift

let filterState: FilterState  = .init()
let hitsTableViewController = CustomHitsTableViewController()
let hitsConnector = HitsConnector<CustomHitModel>(appID: "YourApplicationID",
                                              apiKey: "YourSearchOnlyAPIKey",
                                              indexName: "YourIndexName",
                                              filterState: filterState,
                                              controller: hitsTableViewController)

hitsConnector.searcher.search()

Parameters

searcher · HitsSearcher | PlacesSearcher · required

The Searcher that handles your searches.

interactor · HitsInteractor · required

The logic applied to the hits.

filterState · FilterState

The FilterState for your filters.

appID · ApplicationID · required

The ID of your application.

apiKey · APIKey · required

Your application’s search-only API key.

indexName · IndexName · required

Name of the index to search.

infiniteScrolling · InfiniteScrolling · default: .on(withOffset: 5)

Whether infinite scrolling is enabled. offset defines the threshold for loading the next “page” of results. For example, if the index of the last visible hit is 10, and you setoffset to 3, the engine will display the next page if the hit at index 13 (10+3) isn’t loaded. If set to .off, this parameter turns off infinite scrolling.

showItemsOnEmptyQuery · Bool · default: true

If false, no results are displayed when users haven’t entered any query text.

controller · HitsController · default: nil

The controller interfacing with a concrete hits view.

Low-level API

To fully control the Hits components and connect them manually, use the following components:

• Searcher. Handles your searches.
• HitsInteractor. The logic applied to the hits.
• HitsController. The controller that interfaces with a concrete hits view.
• FilterState. The current state of the filters.

Swift

let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")

let filterState: FilterState  = .init()
let hitsInteractor: HitsInteractor<CustomHitModel> = .init()
let hitsTableViewController = CustomHitsTableViewController()

hitsInteractor.connectSearcher(searcher)
hitsInteractor.connectFilterState(filterState)
hitsInteractor.connectController(hitsTableViewController)
searcher.search()

Now, each time you launch a new search:

• The Searcher receives new results and transmits them to HitsInteractor
• The HitsInteractor parses search results and notifies HitsController
• The HitsController refreshes the view presenting the hits

HitsController

The default controllers, HitsTableViewController and HitsCollectionViewController, let you create a basic Hits view based on UITableView and UICollectionView components from UIKit.

You must configure these controllers using the TableViewCellConfigurable/CollectionViewCellConfigurable implementation protocols that define how your hit model is bound to a concrete cell class. Here is an example of the implementation using the UITableViewCell and CustomHitModel.

Swift

struct CustomCellConfigurator: TableViewCellConfigurable {
  let model: CustomHitModel

  init(model: CustomHitModel, indexPath: IndexPath) {
    self.model = model
  }

  func configure(_ cell: UITableViewCell) {
    cell.textLabel?.text = model.name
  }
}

Define a convenient type alias for your view controller using the CellConfigurable implementation.

Swift

typealias CustomHitsTableViewController = HitsTableViewController<CustomCellConfigurator>

Customization

You can subclass the HitsTableViewController or HitsCollectionViewControllerto customize their behavior.

Swift

class MoreCustomHitsTableViewController: HitsTableViewController<CustomCellConfigurator> {
  ...
}

Customizing your view

The default controllers, HitsTableViewController and HitsCollectionViewController, work well when using native UIKit components with default behaviors.

If you want to use another component as a hits view or introduce some custom behavior to the already provided UIKit component, you can create a controller conforming to the HitsController protocol.

Protocol

var hitsSource: DataSource?:

Reference to an entity providing a list of hits.

func reload():

Function called when a reload of the hits view is required.

func scrollToTop():

Function called when scrolling to the top of the hits view.

Implementation example

Swift

public class CustomHitsTableViewController: NSObject, HitsController {

  public let tableView: UITableView

  public weak var hitsSource: HitsInteractor<Item>?

  public init(tableView: UITableView) {
    self.tableView = tableView
  }

  public func reload() {
    tableView.reloadData()
  }

  public func scrollToTop() {
    guard tableView.numberOfRows(inSection: 0) != 0 else { return }
    let indexPath = IndexPath(row: 0, section: 0)
    self.tableView.scrollToRow(at: indexPath, at: .top, animated: false)
  }

}

SwiftUI

InstantSearch provides the HitsList SwiftUI view, which you can embed in your views. It uses HitsObservableController as a data model. HitsObservableController is an implementation of the HitsController protocol adapted for usage with SwiftUI. HitsObservableController must be connected to the HitsConnector or HitsInteractor like any other HitsController implementation. You should define the view representing a single hit.

Swift

struct HitItem: Codable {
  let name: String
}

struct ContentView: View {

  @ObservedObject var hitsController: HitsObservableController<HitItem>

  var body: some View {
    HitsList(hitsController) { (hit, _) in
      // declare the view representing a single hit
      VStack(alignment: .leading, spacing: 10) {
        Text(hit?.name ?? "")
        Divider()
      }
    } noResults: {
      Text("No Results")
        .frame(maxWidth: .infinity, maxHeight: .infinity)
    }
  }
}

If you prefer to create a custom SwiftUI view that presents the list hits, use HitsObservableController as a data model. It provides the hits property to streamline the design process of your custom SwiftUI view. The notifyAppearanceOfHit(atIndex) function of HitsObservableController might be called on the appearance of each hit to ensure the correct operation of the infinite scrolling feature.

Result metadata and Hit structure

Each hit returned by Algolia is enriched with search metadata, like highlightResult, objectID, and snippetResult. InstantSearch provides an easy way to parse these using the Hit wrapper structure. This generic structure encapsulates your record type and gives strongly typed access to a hit’s metadata.

For example, consider the following record structure:

Swift

struct Movie: Codable {
  let title: String
  let year: Int
}

/* An appropriate structure for representing a record in the following JSON format:

{
  "title": "Titanic",
  "year": 1997
}
*/

Conforming to the Codable protocol, the record is ready to use with the HitsInteractor as follows:

Swift

let hitsInteractor = HitsInteractor<Movie>()

However, by doing this, the engine will ignore all the hit metadata. To keep this metadata, wrap your record structure into the provided Hit structure.

Swift

let hitsInteractor = HitsInteractor<Hit<Movie>>()

You can extract your Movie object by accessing the object field of Hit:

Swift

let movieHit: Hit<Movie> = hitsInteractor.hit(atIndex: ...)
let movie: Movie = movieHit.object

The Hit structure gives access to the following fields:

Swift

// Hit identifier attributed by Algolia
let objectID: String

// Wrapped record object
let object: T

// Snippeted attributes.
let snippetResult: TreeModel<SnippetResult>?

// Highlighted attributes. Each attribute contains an object or an array of objects (if the attribute in question is an array) with the following attributes.
let highlightResult: TreeModel<HighlightResult>?

// Ranking information.
let rankingInfo: RankingInfo?

// Geolocation information
let geolocation: Point?