{"id":13880969,"url":"https://github.com/notsidney/use-algolia","last_synced_at":"2025-07-16T17:31:33.596Z","repository":{"id":57387853,"uuid":"245640514","full_name":"notsidney/use-algolia","owner":"notsidney","description":"Dead-simple React hook to make Algolia search queries. Supports pagination out of the box.","archived":false,"fork":false,"pushed_at":"2021-10-10T10:57:51.000Z","size":1157,"stargazers_count":30,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-21T03:41:27.437Z","etag":null,"topics":["algolia","algolia-search","algoliasearch","react","react-hook","react-hooks"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notsidney.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-07T13:46:14.000Z","updated_at":"2023-02-17T03:30:27.000Z","dependencies_parsed_at":"2022-09-06T08:11:23.967Z","dependency_job_id":null,"html_url":"https://github.com/notsidney/use-algolia","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/notsidney/use-algolia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notsidney%2Fuse-algolia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notsidney%2Fuse-algolia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notsidney%2Fuse-algolia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notsidney%2Fuse-algolia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notsidney","download_url":"https://codeload.github.com/notsidney/use-algolia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notsidney%2Fuse-algolia/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527549,"owners_count":23782480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algolia","algolia-search","algoliasearch","react","react-hook","react-hooks"],"created_at":"2024-08-06T08:03:42.985Z","updated_at":"2025-07-16T17:31:33.168Z","avatar_url":"https://github.com/notsidney.png","language":"TypeScript","readme":"# useAlgolia [![npm latest release](https://badgen.net/npm/v/use-algolia)](https://www.npmjs.com/use-algolia) [![Minified size](https://badgen.net/bundlephobia/min/use-algolia)](https://bundlephobia.com/result?p=use-algolia)\n\nDead-simple React hook to make Algolia search queries. Supports pagination out\nof the box.\n\n![Code snippet](https://raw.githubusercontent.com/notsidney/use-algolia/master/assets/carbon.png)\n\n## Installation\n\nRequires [React](https://www.npmjs.com/react) \u003e= 16.8.0 and\n[algoliasearch](https://www.npmjs.com/algoliasearch) 4.\n\n```\nyarn add react algoliasearch use-algolia\n```\n\n## Usage\n\nPass the Algolia app ID, search API key, and index name to the hook call.\n\nIf you don’t have one of the three on the first hook call, pass in an empty\nstring first.\n[See the example below.](#changing-query-index-or-other-algolia-config)\n\nOptionally, pass the initial request options as the fourth argument.  \nSee https://www.algolia.com/doc/api-reference/search-api-parameters/ for all\noptions.\n\nAccess the returned hits, response, loading, and hasMore from `searchState`.\n\n```ts\nconst [searchState, requestDispatch, getMore] = useAlgolia(\n  APP_ID,\n  SEARCH_KEY,\n  INDEX_NAME,\n  { query: 'construction' }\n);\n\nconst { hits, response, loading, hasMore } = searchState;\n```\n\n### Making new requests\n\nCall `requestDispatch` with options to make a new Algolia search request. Note\nthis will **shallow merge** your previous request options. Making new requests\nwill immediately reset `hits` to an empty array and set `loading` to true.\n\n```ts\nrequestDispatch({ query: 'bin chicken' });\n\n// Create a new request with query: 'bin chicken' AND the filters below.\nrequestDispatch({ filters: 'city:Sydney OR city:Melbourne' });\n\n// Creates a new request, resetting query and filters. Same as retrieving all objects.\nrequestDispatch({ query: '', filters: '' });\n```\n\n### Loading more hits with pagination\n\nCall `getMore` to get the next page of hits. Get all hits from\n`searchState.hits`, not `searchState.response.hits`.\n\nYou could also manually pass in `page` to `requestDispatch` to get a specific\npage or skip pages. Calling `getMore` after doing so will still work.\n\n### Increasing number of hits per page\n\nInclude `hitsPerPage` in your request. Initially set to\n[Algolia’s default of 20](https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/).\n\n```ts\nconst [searchState, requestDispatch, getMore] = useAlgolia(\n  APP_ID,\n  SEARCH_KEY,\n  INDEX_NAME,\n  { hitsPerPage: 100 }\n);\n\n// OR after initial query:\nrequestDispatch({ hitsPerPage: 100 });\n```\n\n### Specifying hit type\n\nIf you’re using TypeScript, pass the hit type as the generic type parameter.\nHits will have `objectID`.\n\n```ts\ntype Hit = {\n  title: string;\n  year: number;\n  actors: string[];\n};\n\nconst [searchState, requestDispatch, getMore] = useAlgolia\u003cHit\u003e(\n  APP_ID,\n  SEARCH_KEY,\n  INDEX_NAME\n);\n\n// hits will have type readonly (Hit \u0026 ObjectWithObjectID)[]\nconst { hits } = searchState;\n```\n\n### Changing query index or other Algolia config\n\nWhen the `appId`, `searchKey`, or `indexName` passed to the hook call updates,\nthe index is reinitialised with the new config.\n\nYou can also use the `setAlgoliaConfig` function returned by the hook:\n\n```ts\nconst [, , , setAlgoliaConfig] = useAlgolia('', '', '');\n\nsetAlgoliaConfig({\n  appId: APP_ID,\n  searchKey: SEARCH_KEY,\n  indexName: INDEX_NAME,\n});\n```\n\nDoing either will automatically do the first query on the new index if all three\nitems are provided.\n\n### Searching for facet values\n\nYou can access the search index created by the hook in `searchState` to call the\n`searchForFacetValues` method. See\nhttps://www.algolia.com/doc/api-reference/api-methods/search-for-facet-values/\n\nNote: `index` may be `null` if one of `appId`, `searchKey`, or `indexName` is\nmissing or invalid in `searchState`.\n[See Changing query index or other Algolia config above.](#changing-query-index-or-other-algolia-config)\n\n```js\nconst [searchState] = useAlgolia('', '', '');\nconst { index } = searchState;\n\nif (index) index.searchForFacetValues('city');\n```\n\n## State\n\n| Key           | Type                           | Description                                                                                                                                                                                                                                                                        |\n| ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **hits**      | `(Hit \u0026 ObjectWithObjectID)[]` | Contains all hits for search query, including all pages retrieved.                                                                                                                                                                                                                 |\n| **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                                                                                                                    |\n| **loading**   | `boolean`                      | True if a request is being loaded, either to load initial request or when loading more hits.                                                                                                                                                                                       |\n| **hasMore**   | `boolean`                      | True if there are more pages to be retrieved.                                                                                                                                                                                                                                      |\n| **appId**     | `string`                       | Algolia App ID.                                                                                                                                                                                                                                                                    |\n| **searchKey** | `string`                       | API key to search the index.                                                                                                                                                                                                                                                       |\n| **indexName** | `string`                       | Algolia index to query.                                                                                                                                                                                                                                                            |\n| **index**     | `SearchIndex` or `null`        | Exposed Algolia search index. Note we use the lite client, which only supports the [`search`](https://www.algolia.com/doc/api-reference/api-methods/search/) and [`searchForFacetValues`](https://www.algolia.com/doc/api-reference/api-methods/search-for-facet-values/) methods. |\n| **request**   | `SearchOptions`                | Exposed search request options passed to the last request. [From previous `requestDispatch` calls.](#making-new-requests)                                                                                                                                                          |\n\n---\n\n## Credits\n\nBased on the original hook by [@shamsmosowi](https://github.com/shamsmosowi).\n\nBootstrapped with [tsdx](https://github.com/jaredpalmer/tsdx) and published with\n[np](https://github.com/sindresorhus/np).\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotsidney%2Fuse-algolia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotsidney%2Fuse-algolia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotsidney%2Fuse-algolia/lists"}