Guides / Building Search UI / Widgets / Customize an existing widget

Create Your Own UI with InstantSearch


InstantSearch Android provides widgets out of the box, which let you add features to your application easily. These widgets provide you several customization options, but sometimes this is not enough. For those cases, InstantSearch Android provides a lower level API by exposing its Searcher and some ViewModels.

Using the Searcher

The Searcher is the main component of InstantSearch Android. It wraps an Algolia API Client and provides a level of abstraction over it.

the Searcher is responsible of all search requests: when Searcher#search() is called, the Searcher will fire a request with the current query, and will forward the search results to its listeners.


A listener is an object implementing one or more of the following interfaces, that will be called after each search request:

You can add a listener to a Searcher by calling Searcher#register{Results,Error}Listener.

To avoid leaking memory, you should call Searcher#destroy() in your Activity/Fragment’s onDestroy method to release existing listeners.

Programmatic API

the Searcher provides a programmatic API to handle several aspects of your search interface:

  • Search: search, setIndex, setQuery
  • Filtering and Faceting: {add,remove,delete}Facet, {add,has,remove,update}FacetRefinement, clearFacetRefinements, {add,get,remove}BooleanFilter, get{Updated}FacetStats
  • State handling (page, requests, …): hasMoreHits, hasPendingRequests, shouldLoadMore & loadMore, reset

You can have several Searcher instances in the same application, for example for doing multi-index search. You can get the default Searcher with get (or get a specific one by specifying the variant parameter), create one with its several create methods, delete a given one with destroy, or delete all existing instances with destroyAll.

Using ViewModels

We provide ViewModels that encapsulate some logic for a specific search concept and provide a way to interact with InstantSearch.


ios This component handles the logic for linking any kind of Search input to one or several InstantSearch interface. You can use it to decouple the logic linking InstantSearch to your search input from the input’s actual look and feel.

See its usage in the multi-index search guide to link a single SearchBox to several InstantSearch interfaces.

Did you find this page helpful?

InstantSearch Android v2