Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aymeric-giraudet/svelte-algolia-instantsearch
A Svelte component library for Algolia InstantSearch.js
https://github.com/aymeric-giraudet/svelte-algolia-instantsearch
algolia instantsearch instantsearch-js instantsearchjs ssr svelte svelte-kit sveltejs sveltekit
Last synced: 3 days ago
JSON representation
A Svelte component library for Algolia InstantSearch.js
- Host: GitHub
- URL: https://github.com/aymeric-giraudet/svelte-algolia-instantsearch
- Owner: aymeric-giraudet
- License: mit
- Created: 2022-05-03T23:57:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-18T19:59:58.000Z (4 months ago)
- Last Synced: 2024-10-30T00:32:49.650Z (2 months ago)
- Topics: algolia, instantsearch, instantsearch-js, instantsearchjs, ssr, svelte, svelte-kit, sveltejs, sveltekit
- Language: Svelte
- Homepage: https://svelte-algolia-instantsearch.vercel.app/
- Size: 266 KB
- Stars: 52
- Watchers: 2
- Forks: 12
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# svelte-algolia-instantsearch
This library is a **community developed** wrapper around [instantsearch.js](https://github.com/algolia/instantsearch) for Svelte.
**It is not affiliated nor backed by Algolia.**
It is meant to be an equivalent of [react-instantsearch-hooks-web](https://github.com/algolia/instantsearch/tree/master/packages/react-instantsearch-hooks-web) for Svelte, exposing a similar API.
> [!IMPORTANT]
> This library **only works with SvelteKit**. It is now the default when you bootstrap a Svelte project.
## Installation
```sh
yarn add svelte-algolia-instantsearch algoliasearch
# or
npm install svelte-algolia-instantsearch algoliasearch
```
## Basic usage
```svelte
import {
InstantSearch,
SearchBox,
Hits,
Pagination,
HitsPerPage,
} from "svelte-algolia-instantsearch";
import algoliasearch from "algoliasearch/lite";
const searchClient = algoliasearch("<YOUR_API_KEY>", "<YOUR_SEARCH_KEY>");
{hit.post_title} by {hit.author_name}
```
## Compatibility with SvelteKit SSR
> **Warning**
> If you are using `pnpm` as a package manager, [please check this issue if you have an error while running your dev script](https://github.com/aymeric-giraudet/svelte-algolia-instantsearch/issues/8#issuecomment-1456561953)
If you want your page to be fully rendered on the server, which is great for SEO, simply add a `+page.server.js` file next to your `+page.svelte` file, which should contain the following lines :
```js
import { getServerState } from "svelte-algolia-instantsearch";
import Page from "./+page.svelte";
export const load = ({ url }) => getServerState(Page, url);
```
Now you can check in your network tab that the page containing hits and facets is fully rendered on the server 😁
## API
### `connect`
The most important part of this library is the `connect` function, which creates and adds a widget to the InstantSearch instance, and returns a Svelte readable store.
Here's an example of how you can use it to build your own components :
```svelte
import { connect } from "svelte-algolia-instantsearch";
import { connectStats } from "instantsearch.js/es/connectors";
const state = connect(connectStats);
$: ({ nbHits, processingTimeMS } = $state);
Found {nbHits} results in {processingTimeMS}ms
```
### Components
It's still a work in progress, but you can use some pre-made components to build your search UI :
- [X] Breadcrumb
- [x] Configure
- [x] ClearRefinements
- [X] CurrentRefinements
- [ ] DynamicWidgets
- [X] HierarchicalMenu
- [x] Highlight
- [x] Hits
- [x] HitsPerPage
- [x] Index
- [x] InfiniteHits
- [X] Menu
- [x] Pagination
- [x] PoweredBy
- [X] RangeInput
- [x] RefinementList
- [x] SearchBox
- [x] Snippet
- [x] SortBy
- [x] Stats
- [x] ToggleRefinement
### `getInstantSearchContext`
This function returns the instance of `InstantSearch` that was instantiated by the `` component.
It can be useful if you want to use the `instantsearch.js` API directly, for example to add a custom middleware.
```svelte
import { getInstantSearchContext } from "$lib";
import { createInsightsMiddleware } from "instantsearch.js/es/middlewares";
import { onMount } from "svelte";
const search = getInstantSearchContext();
onMount(() => {
const insightsMiddleware = createInsightsMiddleware({
/* ... */
});
search.use(insightsMiddleware);
return () => {
search.unuse(insightsMiddleware);
};
});
```