react-meilisearch
TypeScript icon, indicating that this package has built-in type declarations

1.0.1 • Public • Published

React-Meilisearch

The React client api for integrating with Meilisearch Server.
It includes several simple hooks to help you integrate with your search server.
We based it on the meilisearch npm package.

GitHub package.json version (branch) GitHub issues GitHub GitHub repo file count npm bundle size

Install

npm install react-meilisearch

Getting Started

Initialization

First you need to initialize a meilisearch client and connect it to React.

import { MeiliSearchProvider, MeiliSearchClient } from 'react-meilisearch';
import './App.css'

const App = () => {
  const meilisearch = new MeiliSearchClient({
    host: 'http://localhost:7700',
    apiKey: 'masterKey',
  })

  return (
    <MeiliSearchProvider client={meilisearch}>
      // ... rest of App.jsx
    </MeiliSearchProvider>
  )
}

export default App

UseSearch Hook

This hook recieves a query, index and advanced search options, triggers the search and returns the current state of the search.

const { loading, error, data } = useSearch({ index: 'movies', query: 'Comedy' });

Full Example:

In the following example we used the hook along with a 'query' search parameter, using the use-search-params hook.

import { useSearch } from 'react-meilisearch';
import { useSearchParams } from 'react-router-dom';

const UseSearchExample = () => {
    const [searchParams] = useSearchParams();
    const { loading, error, data } = useSearch({ index: 'movies', query: searchParams.get('query') });

    if (loading) return 'Loading...';
    if (error) return 'Error!';
    
    return (
        <div>
            {
                data &&
                <div>results count {data.hits.length}</div>
            }
        </div>
    )
}

export default UseSearchExample;

Parameters

parameter type description default value
query string the query to search by ''
index string the melisearch index to search in ''
options SearchParams meilisearch search options described in the documentation { limit: 30 }

Return Value

parameter type description
loading boolean is the search in progress
error MeiliSearchError / null an error occured in the search request
data SearchResponse<Record<string, any>> / undefined / null the search result
refetch (SearchArguments (same as the hook parameters)) => void method to refetch the search
fetchMore (FetchMoreParameters (same as the hook parameters with the callback updateResult)) => void method to fetch more results, read Infinite Scroll for more details

UseLazySearch Hook

Works the same way as Use Search hook, but returns a search funtion instead of triggering it when the component is mounted.

const [search, { loading, error, data }] = useLazySearch({ index: 'movies' });
search('Comedy');

Full Example:

import { useLazySearch } from 'react-meilisearch';

const UseLazySearchExample = () => {
    const [search, { loading, error, data }] = useLazySearch({ index: 'movies' });

    if (loading) return 'Loading...';
    if (error) return 'Error!';

    return (
        <div>
            <input onChange={(event) => {
                search(event.target.value, { options: {
                    limit: 100
                } });
            }} />
            {
                data &&
                <div>results count {data.hits.length}</div>
            }
        </div>
    )
}

export default UseLazySearchExample;

Parameters

parameter type description default value
query string the query to search by ''
index string the melisearch index to search in ''
options SearchParams meilisearch search options described in the documentation { limit: 30 }

Return Value

parameter type description
search function (SearchArguments (same as the hook parameters)) => void Trigger a search using the given parameters. The function parameters overide the hook parameters
loading boolean is the search in progress
error MeiliSearchError / null an error occured in the search request
data SearchResponse<Record<string, any>> / undefined / null the search result
fetchMore (FetchMoreParameters (same as the hook parameters with the callback updateResult)) => void method to fetch more results, read Infinite Scroll for more details

UseMeilisearchClient Hook

Use this hook to get the meilisearch client and use it's normal methods described in the meilisearch npm package.

const meilisearchClient = useMeiliSearchClient();

Full Example:

import { useState } from 'react';
import { useMeiliSearchClient } from 'react-meilisearch';

const UseMeiliSearchClientExample = () => {
    const meilisearchClient = useMeiliSearchClient();
    const [searchResults, setSearchResults] = useState(null);

    const onChange = (event) => {
        meilisearchClient.index('movies').search(event.target.value)
        .then(setSearchResults);
    }
    
    return (
        <div>
            <input onChange={onChange} />
            {
                searchResults &&
                <div>results count {searchResults.hits.length}</div>
            }
        </div>
    )
}

export default UseMeiliSearchClientExample;

Infinite Scroll

You can easily implement infinite scroll or pagination search using the fetchMore function.
In the example below we used react-infinite-scroll-hook npm package to handle the scroll events. Feel free to change it to whatever you want.

import { useSearch } from 'react-meilisearch';
import useInfiniteScroll  from 'react-infinite-scroll-hook';
import './infiniteScrollExample.css';

const InfiniteScrollExample = ({ query }) => {
    const { loading, error, data, fetchMore } = useSearch({ query, index: 'movies', options: {
        limit: 30,
        offset: 0,
    } });

    const hasNextPage = data && data.estimatedTotalHits > data.hits.length;
    const loadMore = () => fetchMore({ options: { offset: data.hits.length }});

    const [sentryRef, { rootRef }] = useInfiniteScroll({
        loading,
        hasNextPage,
        onLoadMore: loadMore,
        disabled: !!error,
        rootMargin: '0px 0px 200px 0px',
      });

    if (loading) return 'Loading...';
    if (error) return 'Error!';

    return (
        <div className='infinite-scroll' ref={rootRef}>
            {
                data && data.hits.map(hit => (
                    <div key={hit.key}>{hit.title}</div>
                ))
            }
            {
                (loading || hasNextPage) && (
                    <div ref={sentryRef}/>
                  )
            }
        </div>
    )
}

export default InfiniteScrollExample;

The default behavior of the fetchMore result is to concat the result hits with the previous data hits.
You can override this behavior by giving the fetchMore an alternative updateResult callback. Make sure you are returning the new data value.

const updateResult = (prev, fetchMoreResult) => {
    console.log('I am overriding the default updateResult function');
    return (
    {
        ...prev,
        offset: fetchMoreResult.offset,
        hits: [...prev.hits, ...fetchMoreResult.hits]
    })
}
const loadMore = () => fetchMore({ options: {offset: data.hits.length}, updateResult });

Types

All of the meilisearch types are available for you, in addition to these new ones:

type SearchArguments = {
   query: string;
   index: string;
   options: SearchParams;
}

type FetchMoreParameters = SearchArguments & {
   updateResult: (prev: SearchResponse<Record<string, any>>,
                  fetchMoreResult: SearchResponse<Record<string, any>>) 
                   => SearchResponse<Record<string, any>>,
   onError?: (error: MeiliSearchError) => void;
}

type UseSearchResult = {
   loading: boolean;
   error: MeiliSearchError | null;
   data: SearchResponse<Record<string, any>> | undefined | null;
   refetch?: (searchParameters: SearchArguments) => void;
   fetchMore: (searchParameters: FetchMoreParameters) => void;
}

License

MIT

Package Sidebar

Install

npm i react-meilisearch

Weekly Downloads

1

Version

1.0.1

License

MIT

Unpacked Size

21.4 kB

Total Files

31

Last publish

Collaborators

  • itamar-smirra