🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
InstantSearch / iOS / V3 / Api ref

InstantSearch (v3) for iOS

This version of InstantSearch for iOS has been deprecated in favor of the latest version of InstantSearch for iOS.

This widget lets the user perform a text-based query.

Examples

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

Parameters

index

required: false
type: String

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

required: false
type: String

Lets you distinguish between two widgets that target the same index, but with different search parameters.

1
searchBox.variant = "myVariant"

SearchViewModel

ViewModels can be used to customize the rendering of the SearchBox without reimplementing any business logic.

  • 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)
    }

Hits

This widget displays a list of results.

Examples

1
2
3
4
5
6
  var tableView = HitsTableWidget(frame: CGRect.zero, style: .grouped)
  tableView.index = "someIndex"
  tableView.infiniteScrolling = false
  tableView.hitsPerPage = 5
  tableView.showItemsOnEmptyQuery = true
  tableView.remainingItemsBeforeLoading = 3

Parameters

index

required: false
type: String

The index name associated with the widget.

1
searchBox.index = "myIndex"

variant

required: false
type: String

Lets you distinguish between two widgets that target the same index, but with different search parameters.

1
hitsWidget.variant = "myVariant"

hitsPerPage

default: 20
required: false
type: UInt

How many hits are requested and displayed for each search query.

1
hitsWidget.hitsPerPage = 20

infiniteScrolling

default: true
required: false
type: Bool

When false, disables the infinite scroll of the widget.

1
hitsWidget.infiniteScrolling = false

remainingItemsBeforeLoading

default: 5
required: false
type: UInt

When the minimum number of remaining hits is reached, the next page is loaded. For example, if remainingItemsBeforeLoading is set to 10, the next page is loaded when there are less than 10 items below the current visible item.

1
hitsWidget.remainingItemsBeforeLoading = 10

showItemsOnEmptyQuery

default: true
required: false
type: Bool

If false, displays an empty hits widget when there is no query text entered by the user.

1
hitsWidget.showItemsOnEmptyQuery = true

Multi Hits

A widget that displays search results for multiple indices. Each index’s list of results appears in its own section.

Examples

1
2
3
4
var tableView = MultiHitsTableWidget(frame: CGRect.zero, style: .grouped)
tableView.indices = "index1,index2"
tableView.hitsPerSection = "5,3"
tableView.showItemsOnEmptyQuery = true

Parameters

indices

required: true
type: String

The indices associated with this hit. The values are comma-separated with no spaces in between.

1
multiHitsWidget.indices = "index1,index2,index3"

variants

required: false
type: String

Lets you distinguish between two widgets that target the same index, but with different search parameters. The variants are comma-separated with no space in between.

1
multiHitsWidget.variants = "variant1,variant2,vartiant3"

hitsPerSection

default: 20
required: false
type: String

How many hits are requested and displayed for each index, comma-separated.

1
multiHitsWidget.hitsPerSection = "5,3,3"

showItemsOnEmptyQuery

default: true
required: false
type: Bool

When false, displays an empty hits widget when there is no query text entered by the user.

1
multiHitsWidget.showItemsOnEmptyQuery = true

RefinementList

A filtering widget made to display facets that lets the user refine their search results.

Examples

1
2
3
4
5
6
var tableView = RefinementTableWidget(frame: CGRect.zero, style: .grouped)
tableView.attribute = "brand"
tableView.operator = "or"
tableView.limit = 10
tableView.isRefined = true
tableView.sortBy = "count:desc"

Parameters

attribute

required: true
type: String

The faceted attribute used by the widget.

1
refinementWidget.attribute = "brand"

operator

default: 'or'
required: false
type: String

Can either be 'or' or 'and'. Controls whether the results should match any selected value (if or is used) or all selected values (if and is used).

1
refinementWidget.operator = "or"

limit

default: 10
required: false
type: UInt

The maximum amount of facet values to display. If there are more values, displays those with the biggest count.

1
refinementWidget.limit = 12

isRefined

default: true
required: false
type: Bool

Whether the refined values are displayed first or not.

1
refinementWidget.isRefined = true

sortBy

default: 'count:desc'
required: false
type: String

The sort order of the attributes. This attribute accepts the following values:

  • count:asc to sort the facets by ascending count.
  • count:desc to sort the facets by descending count.
  • name:asc to sort the facet values by alphabetical order.
  • name:desc to sort the facet values by reverse alphabetical order.
1
refinementWidget.sortBy = "count:desc"

Numeric Filters

Widget that handle numeric filters.

Examples

1
2
3
4
var slider = SliderWidget(frame: CGRect)
slider.attribute = "price"
slider.operator = ">"
slider.inclusive = true

Parameters

attribute

required: true
type: String

The numeric attribute used by the widget.

1
numericWidget.attribute = "price"

operator

required: true
type: String

The numeric operator to apply to the filter. Possible ones are \<, \<=, ==, !=, \>= and \>.

1
numericWidget.operator = ">"

inclusive

default: true
required: false
type: Bool

Whether the refinement is inclusive or exclusive.

1
numericWidget.inclusive = true

OneValueSwitchWidget

A widget that provides an on/off filtering feature based on an attribute value.

Examples

1
2
3
let oneValueSwitchWidget = OneValueSwitchWidget(frame: CGRect)
oneValueSwitchWidget.attribute = "shipping"
oneValueSwitchWidget.valueOn = "premium"

Parameters

attribute

required: true
type: String

The attribute used by the widget.

1
oneValueSwitchWidget.attribute = "shipping"

valueOn

default: ''
required: true
type: String

The value when the toggle is on.

1
oneValueSwitchWidget.valueOn = "premium"

inclusive

default: true
required: false
type: Bool

Whether the refinement is inclusive or exclusive.

1
oneValueSwitchWidget.inclusive = true

Stats

Widget that displays the total number of matching hits and the time it took to get them.

Examples

1
2
3
var statsWidget = StatsLabelWidget(frame: CGRect)
statsWidget.resultTemplate = "{nbHits} results in {processingTimeMS}"
statsWidget.errorText = "Error while loading"

Parameters

resultTemplate

default: "{nbHits} results"
required: false
type: String

What the widget displays when a search request returns successfully. It takes the form of a templated string with the following variables to replace:

  • {nbHits}: the hit count for the current query.
  • {processingTimeMS}: the time the server took to process the request, in milliseconds.
  • {hitsPerPage}: the maximum number of hits returned per page.
  • {nbPages}: the number of pages corresponding to the number of hits.
  • {page}: the index of the current page (zero-based).
  • {query}: the query text.
1
statsWidget.resultTemplate = "{nbHits} results in {processingTimeMS}"

errorText

default: ''
required: false
type: String

What the widget displays when a search query returns with an error.

1
statsWidget.errorText = "Error while loading"
Did you find this page helpful?