SearchProvider

The SearchProvider should be used as a wrapper for the entire application to provide a way to share application state between hooks, for example, the current query, active filters or the search response.

import { SearchProvider } from '@sajari/react-hooks';

import { SearchProvider } from '@sajari/react-hooks';

Usage

It must wrap any components where you are using hooks, usually this is done in an App or index file. You must also specify the pipeline you wish to query.

<SearchProvider
  search={{
    pipeline: new Pipeline(
      {
        account: '<Your account ID>',
        collection: '<Your collection ID>',
      },
      '<Your pipeline name>',
    ),
  }}
>
  <YourApp />
</SearchProvider>

<SearchProvider
  search={{
    pipeline: new Pipeline(
      {
        account: '<Your account ID>',
        collection: '<Your collection ID>',
      },
      '<Your pipeline name>',
    ),
  }}
>
  <YourApp />
</SearchProvider>

Replace the placeholders with your account and collection IDs from the collection crendentials section in the console.
Replace the pipeline name placeholder with the pipeline you'd like to use to query.

Sync URL state

Enable the syncURLState prop to synchronize the state of your search UI with the browser URL. By default, it works out of the box for syncing the state of query, filters, sort and resultsPerPage while providing a support for external params.

Editable Example

Suggestions

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );
  const fields = new FieldDictionary({
    title: 'name',
    subtitle: (data) => data.level4 || data.level3 || data.level2 || data.level1 || data.brand,
  });
  const brandFilter = new FilterBuilder({
    name: 'brand',
    field: 'brand',
  });
  const categoryFilter = new FilterBuilder({
    name: 'level1',
    field: 'level1',
  });
  const colorFilter = new FilterBuilder({
    name: 'color',
    field: 'imageTags',
    array: true,
  });
  const priceFilter = new RangeFilterBuilder({
    name: 'price',
    field: 'price',
  });
  const ratingFilter = new FilterBuilder({
    name: 'rating',
    field: 'rating',
  });
  const App = React.memo(() => {
    const { searched } = useSearchContext();
    const { viewType, setViewType } = useSearchUIContext();
    return (
      <>
        <Input />
        <div className="flex items-center justify-end mt-3">
          <Summary size="sm" />
          <div className="flex space-x-4 ml-auto">
            <Sorting
              options={[
                { name: 'Most relevant', value: '' },
                { name: 'Brand: A to Z', value: 'brand' },
                { name: 'Brand: Z to A', value: '-brand' },
                { name: 'Rating: Low to High', value: 'rating' },
                { name: 'Rating: High to Low', value: '-rating' },
                { name: 'Popularity', value: 'popularity' },
              ]}
              size="sm"
            />
            <ResultsPerPage size="sm" />
            <ViewType size="sm" />
          </div>
        </div>
        <div className="flex mt-6">
          {searched && (
            <div className="w-1/4 pr-4 border-gray-100 border-r space-y-6">
              <Filter type="list" name="brand" title="Brand" searchable />
              <Filter type="list" name="level1" title="Category" searchable />
              <Filter type="range" name="price" title="Price" format="price" />
              <Filter type="color" name="color" title="Color" />
              <Filter type="rating" name="rating" title="Rating" />
            </div>
          )}
          <div className="flex-1 pl-4">
            <Results />
          </div>
        </div>
        <div className="sticky bottom-0 p-6">
          <Pagination />
        </div>
      </>
    );
  });
  return (
    <SearchProvider
      search={{
        pipeline,
        fields,
        filters: [categoryFilter, priceFilter, colorFilter, ratingFilter, brandFilter],
      }}
      searchOnLoad
      syncURLState
    >
      <App />
    </SearchProvider>
  );
}

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );
  const fields = new FieldDictionary({
    title: 'name',
    subtitle: (data) => data.level4 || data.level3 || data.level2 || data.level1 || data.brand,
  });
  const brandFilter = new FilterBuilder({
    name: 'brand',
    field: 'brand',
  });
  const categoryFilter = new FilterBuilder({
    name: 'level1',
    field: 'level1',
  });
  const colorFilter = new FilterBuilder({
    name: 'color',
    field: 'imageTags',
    array: true,
  });
  const priceFilter = new RangeFilterBuilder({
    name: 'price',
    field: 'price',
  });
  const ratingFilter = new FilterBuilder({
    name: 'rating',
    field: 'rating',
  });
  const App = React.memo(() => {
    const { searched } = useSearchContext();
    const { viewType, setViewType } = useSearchUIContext();
    return (
      <>
        <Input />
        <div className="flex items-center justify-end mt-3">
          <Summary size="sm" />
          <div className="flex space-x-4 ml-auto">
            <Sorting
              options={[
                { name: 'Most relevant', value: '' },
                { name: 'Brand: A to Z', value: 'brand' },
                { name: 'Brand: Z to A', value: '-brand' },
                { name: 'Rating: Low to High', value: 'rating' },
                { name: 'Rating: High to Low', value: '-rating' },
                { name: 'Popularity', value: 'popularity' },
              ]}
              size="sm"
            />
            <ResultsPerPage size="sm" />
            <ViewType size="sm" />
          </div>
        </div>
        <div className="flex mt-6">
          {searched && (
            <div className="w-1/4 pr-4 border-gray-100 border-r space-y-6">
              <Filter type="list" name="brand" title="Brand" searchable />
              <Filter type="list" name="level1" title="Category" searchable />
              <Filter type="range" name="price" title="Price" format="price" />
              <Filter type="color" name="color" title="Color" />
              <Filter type="rating" name="rating" title="Rating" />
            </div>
          )}
          <div className="flex-1 pl-4">
            <Results />
          </div>
        </div>
        <div className="sticky bottom-0 p-6">
          <Pagination />
        </div>
      </>
    );
  });
  return (
    <SearchProvider
      search={{
        pipeline,
        fields,
        filters: [categoryFilter, priceFilter, colorFilter, ratingFilter, brandFilter],
      }}
      searchOnLoad
      syncURLState
    >
      <App />
    </SearchProvider>
  );
}

Note

It is recommended that you only need to use SearchProvider once at the root of your application, if you find the need to use multiple collections then having multiple SearchProviders would be okay too. You shouldn't nest SearchProviders because each provider will create a separate new context which makes components beneath it (Pagination, Sorting) not behaving as they should.

Props

Name	Type	Default	Description
`search`	`ProviderPipelineConfig`		A pipeline configuration for search requests.
`autocomplete`	`ProviderPipelineConfig`		A pipeline configuration for autocomplete and typeahead requests. This is optional, by default we'll use an `autocomplete` pipeline.
`searchOnLoad`	`boolean`		Whether to search on initial load. Note: if you're also calling the `useSearch` hook in your app, you'll make two search requests.
`initialResponse`	`string`		An initial search response in JSON format, useful for server-side rendering.
`defaultFilter`	`string`		A default filter to apply to all search requests.
`syncURLState`	`boolean` \| `SyncURLState`	false	Allow to synchronize the state of your search UI with the browser URL.

ProviderPipelineConfig

Name	Type	Description
`pipeline`	`Pipeline`	Config which pipeline to use for search queries.
`variables`	`Variables`	A simple key -> value pair object used for every search request. It includes critical data such as the query, results per page, current page, etc.
`config`	`Config`	Define mapping between key/value pair params to be sent with each and every request.
`fields`	`FieldDictionary`	A configuration is used to map fields in your data to the required fields to display in the UI.
`filters`	`(FilterBuilder` or `RangeFilterBuilder)[]`	A list of filters is used to navigate and find relevant results.

SyncURLState

Name	Type	Default	Description
`delay`	`number`	500	The delay time to synchronize the param to URL
`replace`	`boolean`	false	If `true`, modifies the current history entry, replacing it with the new state object
`extendedParams`	`ExtendedParam[]`	false	The extend params to be synchronized with the URL query params
`paramKeys`	`ParamKeys`	`{ q: 'q', resultsPerPage: 'show', page: 'page', sort: 'sort'}`	The names of the URL query params

ExtendedParam

Name	Type	Description
`key`	`string`	Key of the param
`callback`	`string`	Callback when the URL param changes
`defaultValue`	`string` \| `number` \| `boolean` \| `string[]` \| `number[]` \| `boolean[]`	Default value of the param
`value`	`string` \| `number` \| `boolean` \| `string[]` \| `number[]` \| `boolean[]`	Current value of the param

ParamKeys

Name	Type	Default	Description
`q`	`string`	'q'	The name of the search query URL param
`resultsPerPage`	`string`	'show'	The name of the total results per page URL param
`page`	`string`	'page'	The name of the current page URL param
`sort`	`string`	'sort'	The name of the sort URL param