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.

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