useAlgolia

Dead-simple React hook to make Algolia search queries. Supports pagination out of the box.

Installation

Requires React >= 16.8.0 and algoliasearch 4.

yarn add react algoliasearch use-algolia

Usage

Pass the Algolia app ID, search API key, and index name to the hook call.

If you don’t have one of the three on the first hook call, pass in an empty string first. See the example below.

Optionally, pass the initial request options as the fourth argument.

See https://www.algolia.com/doc/api-reference/search-api-parameters/ for all options.

Access the returned hits, response, loading, and hasMore from searchState .

; ;

Making new requests

Call requestDispatch with options to make a new Algolia search request. Note this will shallow merge your previous request options. Making new requests will immediately reset hits to an empty array and set loading to true.

requestDispatch ( ) ; requestDispatch ( ) ; requestDispatch ( ) ;

Loading more hits with pagination

Call getMore to get the next page of hits. Get all hits from searchState.hits , not searchState.response.hits .

You could also manually pass in page to requestDispatch to get a specific page or skip pages. Calling getMore after doing so will still work.

Increasing number of hits per page

Include hitsPerPage in your request. Initially set to Algolia’s default of 20.

; requestDispatch ( ) ;

Specifying hit type

If you’re using TypeScript, pass the hit type as the generic type parameter. Hits will have objectID .

type Hit = { ; ; ; } ; ; ;

Changing query index or other Algolia config

When the appId , searchKey , or indexName passed to the hook call updates, the index is reinitialised with the new config.

You can also use the setAlgoliaConfig function returned by the hook:

; setAlgoliaConfig ( ) ;

Doing either will automatically do the first query on the new index if all three items are provided.

Searching for facet values

You can access the search index created by the hook in searchState to call the searchForFacetValues method. See https://www.algolia.com/doc/api-reference/api-methods/search-for-facet-values/

Note: index may be null if one of appId , searchKey , or indexName is missing or invalid in searchState . See Changing query index or other Algolia config above.

const [ searchState ] = useAlgolia ( ' ' , ' ' , ' ' ) ; const { index } = searchState ; if ( index ) index . searchForFacetValues ( ' city ' ) ;

State

Key Type Description hits (Hit & ObjectWithObjectID)[] Contains all hits for search query, including all pages retrieved. response SearchResponse or null Response to last query. Contains only last page of hits retrieved. Initially null . See https://www.algolia.com/doc/api-reference/api-methods/search/#response loading boolean True if a request is being loaded, either to load initial request or when loading more hits. hasMore boolean True if there are more pages to be retrieved. appId string Algolia App ID. searchKey string API key to search the index. indexName string Algolia index to query. index SearchIndex or null Exposed Algolia search index. Note we use the lite client, which only supports the search and searchForFacetValues methods. request SearchOptions Exposed search request options passed to the last request. From previous requestDispatch calls.

Credits

Based on the original hook by @shamsmosowi.

Bootstrapped with tsdx and published with np.

useAlgolia is created by Antler Engineering.

Also check out our open-source project Firetable: an accessible and powerful content management experience for Google Cloud with a spreadsheet-like UI for Firestore.

About Antler

At Antler, we identify and invest in exceptional people.

We’re a global startup generator and early-stage VC firm that builds groundbreaking technology companies.

Apply now to be part of a global cohort of tech founders.