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

InstantSearch (v1) for Android

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

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

Examples

1
2
3
4
5
6
7
8
<com.algolia.instantsearch.ui.views.SearchBox
  android:id="@+id/searchBox"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:iconifiedByDefault="false"
  android:queryHint="Search"
  algolia:autofocus="false"
  algolia:submitButtonEnabled="false" />
1
2
SearchBox searchBox = new SearchBox(this);
layout.addView(searchBox);

Parameters

autofocus

required: false
default: false
type: boolean

Whether the widget should request the user’s focus when displayed.

1
algolia:autofocus="true"

submitButtonEnabled

required: false
default: false
type: String

Whether the widget should display a submit button. This button is hidden by default: displaying a submit button is usually misleading because every keystroke updates the results.

1
algolia:submitButtonEnabled="true"

variant

required: false
default: null
type: string

Identifies the widget group that this widget is part of. If specified, this widget is only linked to other widgets that have the same identifier. See Multi-Index Searches.

1
algolia:submitButtonEnabled="true"

Hits

This widget displays a list of results.

Examples

1
2
3
4
5
6
7
<com.algolia.instantsearch.ui.views.Hits
    android:id="@+id/hits"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    algolia:remainingItemsBeforeLoading="5"
    algolia:autoHideKeyboard="true"
    algolia:itemLayout="@layout/hits_item" />
1
2
SearchBox searchBox = new SearchBox(this);
layout.addView(searchBox);

Parameters

itemLayout

required: true
type: reference

Determines the appearance of search results by defining the layout that records should use. Binds the given layout to each result received from its Searcher, so that attributes are displayed in the appropriate Views.

Note: you must enable Data Binding for this feature to work.

1
algolia:itemLayout="@layout/hits_item"

infiniteScroll

required: false
default: true
type: boolean

If false, disables the infinite scroll of the widget.

1
algolia:infiniteScroll="false"

remainingItemsBeforeLoading

default: 5
required: false
type: integer

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
algolia:remainingItemsBeforeLoading="10"

autoHideKeyboard

default: false
required: false
type: boolean

Whether the keyboard should close when the user scrolls down.

1
algolia:autoHideKeyboard="true"

variant

default: null
required: false
type: string

Identifies the widget group that this widget is part of. If specified, this widget is only linked to other widgets that have the same variant. See Multi-Index Searches.

1
algolia:variant="actors"

RefinementList

A filtering widget that displays facets and lets users refine their search results.

Examples

1
2
3
4
5
6
7
8
9
<com.algolia.instantsearch.views.RefinementList
  android:id="@+id/refinements"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  algolia:attribute="city"
  algolia:limit="10"
  algolia:operation="or"
  algolia:sortBy="['isRefined', 'count:desc']"
/>

Parameters

attribute

required: true
type: string

The faceted attribute used by the widget.

1
algolia:attribute="city"

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
algolia:operation="and"

sortBy

default: ["isRefined","count:desc","name:asc"]
required: false
type: String

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

  • count:asc
  • count:desc
  • name:asc
  • name:desc
  • isRefined

Array<string>

1
algolia:sortBy="['isRefined', 'count:desc']"

string

1
algolia:sortBy="isRefined"

limit

default: 10
required: false
type: integer

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

1
algolia:limit=5

variant

default: null
required: false
type: string

Identifies the widget group that this widget is part of. If specified, this widget is only linked to other widgets that have the same variant. See Multi-Index Searches.

1
algolia:variant="actors"

Toggles

Toggles are widgets for filtering faceted attributes. There are currently two kinds of Toggles:

  • OneValueToggle: a SwitchCompat-based widget with an assigned attribute that toggles between filtering and not filtering on a specific value.
  • TwoValuesToggle: a SwitchCompat-based widget with an assigned attribute that toggles between filtering on two possible values.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<com.algolia.instantsearch.ui.views.OneValueToggle
    android:id="@+id/oneValueToggle"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    algolia:attribute="category"
    algolia:value="book"
    algolia:template="filter {name} for {value}: {isRefined}"/>

<com.algolia.instantsearch.ui.views.TwoValuesToggle
    android:id="@+id/twoValuesToggle"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    algolia:attribute="category"
    algolia:valueOn="book"
    algolia:valueOff="book"
    algolia:template="filtering {name} for {value}"/>

Parameters

attribute

required: true
type: String

The faceted attribute that is refined by the toggle.

1
algolia:attribute="category"

template

default: null
required: true
type: String

Used as the Toggle’s text (if specified). Accepts the following templates:

  • {name}: the attribute name.
  • {value}: the refined value.
  • {isRefined} (only for OneValueToggle): true when refining, false otherwise.

OneValueToggle

1
algolia:template="filter {name} for {value}: {isRefined}"

TwoValuesToggle

1
algolia:template="filtering on {name}: {value}"

autoHide

default: false
required: false
type: boolean

Whether the toggle should be hidden when there are no results.

1
algolia:autoHide="true"

variant

default: null
required: false
type: string

Identifies the widget group that this widget is part of. If specified, this widget is only linked to other widgets that have the same variant. See Multi-Index Searches.

1
algolia:variant="actors"

OneValueToggle Parameters

value

required: true
type: string

The value to be applied when filtering the attribute.

1
algolia:value="book"

TwoValuesToggle Parameters

valueOn

required: true
type: string

The value to be applied for attribute when the toggle is on.

1
algolia:valueOn="book"

valueOff

required: true
type: string

The value to be applied for attribute when the toggle is off.

1
algolia:valueOff="magazine"

Numeric Selector

Displays a dropdown menu that offers several refinement values for a specific attribute.

Examples

1
2
3
4
5
6
7
8
9
10
 <com.algolia.instantsearch.ui.views.filters.NumericSelector
    android:id="@+id/numericSelector"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    algolia:labels="&lt; 10€, &lt; 100€, &lt; 1000€"
    algolia:values="10, 100, 1000"
    algolia:defaultLabel="Any price"
    algolia:operator="lt"
    algolia:autoHide="true"
  />
1
2
SearchBox searchBox = new SearchBox(this);
layout.addView(searchBox);

Parameters

attribute

required: true
type: string

The faceted attribute that is used by the widget.

1
algolia:attribute="price"

labels

required: true
type: string

The labels to display for each refinement option.

1
algolia:labels="&lt; 10€, &lt; 100€, &lt; 1000€"

values

required: true
type: string

The values to refine with for each option.

1
algolia:values="10, 100, 1000"

operator

required: true
type: string

The operator to use for refining, in the form lt (\<), le (\<=), eq (=), etc.

1
algolia:operator="lt"

defaultLabel

default: null
required: false
type: string

The default label that is displayed when no refinement is selected.

1
algolia:defaultLabel="Any price"

autoHide

default: false
required: false
type: boolean

Whether the widget should be hidden when there are no results.

1
algolia:autoHide="true"

variant

default: null
required: false
type: string

Identifies the widget group that this widget is part of. If specified, this widget is only linked to other widgets that have the same variant. See Multi-Index Searches.

1
algolia:variant="actors"

Stats

Displays the total number of matching hits and the time the search took.

Examples

1
2
3
4
5
6
7
<com.algolia.instantsearch.ui.views.Stats
    android:id="@+id/hitCount"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:layout_weight="1"
    algolia:errorTemplate="@string/error_template"
    algolia:resultTemplate="@string/result_template" />

Parameters

resultTemplate

default: "{nbHits} results found in {processingTimeMS} ms"
required: true
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
algolia:resultTemplate="{nbHits} results found in {processingTimeMS} ms"

errorTemplate

default: null
required: false
type: String

What the widget displays when a search query returns with an error. It takes the form of a templated string with the following templates to replace:

  • {error}: the error message
  • {query}: the query text
1
algolia:errorTemplate="There was an error ({error}), please try again"

autoHide

default: false
required: false
type: boolean

Whether the widget should be hidden when there are no results.

1
algolia:autoHide="true"

variant

default: null
required: false
type: string

Identifies the widget group that this widget is part of. If specified, this widget is only linked to other widgets that have the same variant. See Multi-Index Searches.

1
algolia:variant="actors"
Did you find this page helpful?