TypeScript JavaScript
Clone or download

README.md

Sajari React SDK

npm (scoped) Travis license

@sajari/sdk-react is a client side javascript library of React Components for the Sajari search platform to help build fast and powerful search interfaces.

React provides a simple and elegant way to structure user interfaces. The Sajari React SDK provides a way to seamlessly integrate the Sajari platform into any web-based app through the use of easily composable Components.

We also provide a vanilla Sajari JS library here.

Table of contents

Examples

It's easy to get up and running using one of our examples as a starting point. They're pre-configured with all the correct dependencies, so all you need to do is copy the example directory into your own workspace and you're on your way!

  • Basic: basic search box, hit enter to search (View, Edit).
  • Typeahead with Instant Search: search box with typeahead autocomplete and instant search enabled (View, Edit).
  • Suggestions Dropdown: search box with drop-down autocomplete suggestions (View, Edit).
  • Radio/checkbox: radio/checkbox filtering (View, Edit).

Setup

NPM

We distribute the @sajari/sdk-react library through NPM (note: NPM is only required for downloading the library). The SDK is made to be used from the browser.

$ npm install --save @sajari/sdk-react

Documentation

For full documentation, see sajari-sdk-react.netlify.com.

Quick reference

This library includes a standard set of components for building search interfaces.

Setting up API calls

Before you can use any components, you'll need to initialise a Pipeline for handling search requests to the API:

import { Pipeline } from "@sajari/sdk-react";

// Create a pipeline for running searches.
const pipeline = new Pipeline(
  {
    project: "<your-project>", 
    collection: "<your-collection>"
  },
  "<pipeline-name>" // typically "website"
);

// Now you're ready to perform a search.
pipeline.search({
  "q": "awesome articles",
});

Provider

<Provider /> handles the request-response lifecycle for searches. It performs queries and passes the response to UI components so that they can be updated.

import { Provider, Pipeline, Values } from "@sajari/sdk-react";

const pipeline = new Pipeline(
  {
    project: "<your-project>", 
    collection: "<your-collection>"
  },
  "<your-pipeline>"
);

const values = new Values();


ReactDOM.render(
  <Provider search={{pipeline, values}}>
    {/* Your application code here */}
  </Provider>,
  document.getElementById("root")
)

Input

The Input component creates a text-box which performs searches as the user types. It is customizable through the use of props, options include rendering autocomplete suggestions back in the input box, or rendering autocomplete suggestions in a drop-down list.

import { Input } from "@sajari/sdk-react";

/* default props */
<Input />

/* typeahead */
<Input inputMode="typeahead" />

/* suggestions */
<Input inputMode="typeahead" dropdownMode="suggestions" />

Handling results

A typical search result UI panel includes a summary of the search (i.e. "10 results found for X"), including options to fix spellings or suggested alternatives, and a paginated list of results. We include components for all of these pieces so it's easy to get started.

A standard search response handler would look something like this:

<Response>
  <Summary />
  <Results />
  <Paginator />
</Response>

<Response/>

The <Response /> component acts as a wrapper for components that render response information. It doesn't render its children if the pipeline Response is empty (i.e. the initial pre-search state, or after pipeline.clearResponse() has been called).

<Results />

The <Results /> component can also take a custom renderer which will be used to render its individual results. See the custom result renderer example for more details.

Facets & Filtering

For documentaion on Facets & Filtering, see sajari-sdk-react.netlify.com/facets-and-filtering

License

We use the MIT license

Browser support

The browser support is dependent on the React library, which currently supports recent versions of Chrome, Firefox, Sajari, Opera, and IE9+. (17/8/2016)