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.

const [searchState, requestDispatch, getMore] = useAlgolia(
  APP_ID,
  SEARCH_KEY,
  INDEX_NAME,
  { query: 'construction' }
);

const { hits, response, loading, hasMore } = 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({ query: 'bin chicken' });

// Create a new request with query: 'bin chicken' AND the filters below.
requestDispatch({ filters: 'city:Sydney OR city:Melbourne' });

// Creates a new request, resetting query and filters. Same as retrieving all objects.
requestDispatch({ query: '', filters: '' });

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.

const [searchState, requestDispatch, getMore] = useAlgolia(
  APP_ID,
  SEARCH_KEY,
  INDEX_NAME,
  { hitsPerPage: 100 }
);

// OR after initial query:
requestDispatch({ hitsPerPage: 100 });

Specifying hit type

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

type Hit = {
  title: string;
  year: number;
  actors: string[];
};

const [searchState, requestDispatch, getMore] = useAlgolia<Hit>(
  APP_ID,
  SEARCH_KEY,
  INDEX_NAME
);

// hits will have type readonly (Hit & ObjectWithObjectID)[]
const { hits } = searchState;

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:

const [, , , setAlgoliaConfig] = useAlgolia('', '', '');

setAlgoliaConfig({
  appId: APP_ID,
  searchKey: SEARCH_KEY,
  indexName: INDEX_NAME,
});

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.