InstantSearch (v3) for iOS

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

SearchBox# Found an issue? Edit this guide A Edit this guide

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#

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#

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# Found an issue? Edit this guide A Edit this guide

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#

The index name associated with the widget.

1
searchBox.index = "myIndex"

variant#

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

1
hitsWidget.variant = "myVariant"

hitsPerPage#

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

1
hitsWidget.hitsPerPage = 20

infiniteScrolling#

When false, disables the infinite scroll of the widget.

1
hitsWidget.infiniteScrolling = false

remainingItemsBeforeLoading#

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#

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

1
hitsWidget.showItemsOnEmptyQuery = true

Multi Hits# Found an issue? Edit this guide A Edit this guide

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#

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

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

variants#

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#

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

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

showItemsOnEmptyQuery#

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

1
multiHitsWidget.showItemsOnEmptyQuery = true

RefinementList# Found an issue? Edit this guide A Edit this guide

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#

The faceted attribute used by the widget.

1
refinementWidget.attribute = "brand"

operator#

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#

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

1
refinementWidget.limit = 12

isRefined#

Whether the refined values are displayed first or not.

1
refinementWidget.isRefined = true

sortBy#

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# Found an issue? Edit this guide A Edit this guide

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#

The numeric attribute used by the widget.

1
numericWidget.attribute = "price"

operator#

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

1
numericWidget.operator = ">"

inclusive#

Whether the refinement is inclusive or exclusive.

1
numericWidget.inclusive = true

OneValueSwitchWidget# Found an issue? Edit this guide A Edit this guide

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#

The attribute used by the widget.

1
oneValueSwitchWidget.attribute = "shipping"

valueOn#

The value when the toggle is on.

1
oneValueSwitchWidget.valueOn = "premium"

inclusive#

Whether the refinement is inclusive or exclusive.

1
oneValueSwitchWidget.inclusive = true

Stats# Found an issue? Edit this guide A Edit this guide

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#

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#

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

1
statsWidget.errorText = "Error while loading"