Skip to content
Libraries for the fast development of modern, engaging search experiences.
Branch: master
Clone or download
JasonStoltz Removed elasticsearch connector (#247)
This is to reduce confusion. The connector was experimental and
is not recommended for use.
Latest commit 2de7479 May 23, 2019

README.md

CircleCI buidl BETA Gitter

Libraries for the fast development of modern, engaging search experiences. 🎉

Contents


About Search UI 🚀

Search UI allows you to quickly implement search experiences without re-inventing the wheel.

It supports React and works with any search API.

Features 👍

  • You know, for search - Maintained by Elastic, the team behind Elasticsearch.
  • Speedy Implementation - Build a complete search experience with a few lines of code.
  • Customizable - Tune the components, markup, styles, and behaviors to your liking.
  • Smart URLs - Searches, paging, filtering, and more, are captured in the URL for direct result linking.
  • Headless - Leverage our application logic, provide your own components or views.
  • Flexible - Not just for React. Use with any JavaScript library, even vanilla JavaScript.

Demos

We have 3 live demos deployed for reference. They each use the same UI code, but with different Search API Connectors:

Getting started 🐣

Looking for a great search API? Elastic App Search has a slick dashboard, powerful features, and leading relevance.

Install React Search UI and the App Search connector.

# Install React Search UI and a Connector, like the Elastic App Search Connector
npm install --save @elastic/react-search-ui @elastic/search-ui-app-search-connector

Note: Search UI is in beta. We do not recommend production use.

Creating a search experience

Use out of the box components, styles, and layouts to build a search experience in a matter of minutes.

import React from "react";
import AppSearchAPIConnector from "@elastic/search-ui-app-search-connector";
import { SearchProvider, Results, SearchBox } from "@elastic/react-search-ui";
import { Layout } from "@elastic/react-search-ui-views";

import "@elastic/react-search-ui-views/lib/styles/styles.css";

const connector = new AppSearchAPIConnector({
  searchKey: "search-371auk61r2bwqtdzocdgutmg",
  engineName: "search-ui-examples",
  hostIdentifier: "host-2376rb"
});

export default function App() {
  return (
    <SearchProvider
      config={{
        apiConnector: connector
      }}
    >
      {() => (
        <div className="App">
          <Layout
            header={<SearchBox />}
            bodyContent={<Results titleField="title" urlField="nps_link" />}
          />
        </div>
      )}
    </SearchProvider>
  );
}

Or go "headless", and take complete control over the look and feel of your search experience.

<SearchProvider config={config}>
  {({ searchTerm, setSearchTerm, results }) => {
    return (
      <div>
        <input
          value={searchTerm}
          onChange={e => setSearchTerm(e.target.value)}
        />
        {results.map(r => (
          <div key={r.id.raw}>{r.title.raw}</div>
        ))}
      </div>
    );
  }}
</SearchProvider>

A search experience built with Search UI is composed of the following layers:

  1. A Search API
  2. A Connector
  3. A SearchProvider
  4. Components
  5. Styles and Layout
Styles and Layout -> Components -> SearchProvider -> Connector -> Search API

1. Search API

A Search API is any API that you use to search data; examples being Elasticsearch, Elastic App Search, and Elastic Site Search.

In order to use Search UI you'll need to have your data indexed into a service like this before you can start searching.

2. Connectors

Connectors are modules that tell Search UI how to connect and communicate with your Search API. They generate Search API calls for you so that Search UI will "just work", right out of the box.

Search UI currently provides two Connectors:

  1. Elastic App Search: search-ui-app-search-connector
  2. Elastic Site Search: search-ui-site-search-connector

The example search experience above uses the Elastic App Search Connector:

const connector = new AppSearchAPIConnector({
  searchKey: "search-371auk61r2bwqtdzocdgutmg",
  engineName: "search-ui-examples",
  hostIdentifier: "host-2376rb"
});

Search UI can connect to any web based Search API. Read the advanced README for more information.

3. SearchProvider

SearchProvider is the top level component in your Search UI implementation. It is where you configure your search experience, and it ties all of your components together so that they work as a cohesive application.

<SearchProvider
  config={{
    apiConnector: connector
  }}
>
  {() => <div className="App">{/* Place Components here! */}</div>}
</SearchProvider>

For more on components, continue to the next section!

While components can be handy, your search experience sometimes has requirements that don't quite fit what components provide "out of the box". In this case, it can be convenient to work directly with the "actions" and "state" provided by something we call the "SearchDriver". SearchProvider exposes those in a Render Prop, which gives you maximum flexibility over your experience.

<SearchProvider
  config={{
    apiConnector: connector
  }}
>
  {({ searchTerm, setSearchTerm }) => (
    <div className="App">{/* Work directly with state and actions! */}</div>
  )}
</SearchProvider>

To learn more about "state", "actions", and our "SearchDriver", Read the Headless Core Guide

SearchProvider is lightweight, but it's deeply configurable.

Read the Advanced Configuration Guide.

4. Components

Components are the building blocks from which you craft your search experience.

Each Component - like SearchBox and Results - need only be a child of the SearchProvider object:

<SearchProvider
  config={{
    apiConnector: connector
  }}
>
  {() => (
    <div className="App">
      <div className="Header">
        <SearchBox />
      </div>
      <div className="Body">
        <Results titleField="title" urlField="nps_link" />
      </div>
    </div>
  )}
</SearchProvider>

The following Components are available:

  • SearchBox
  • Results
  • Result
  • ResultsPerPage
  • Facet
  • Sorting
  • Paging
  • PagingInfo
  • ErrorBoundary

Read the Component Reference for a breakdown.

5. Styles and Layout

For basic styles, include:

import "@elastic/react-search-ui-views/lib/styles/styles.css";

For a basic layout, which helps quickly get a UI bootstrapped, use the Layout Component.

import { Layout } from "@elastic/react-search-ui-views";

<Layout header={<SearchBox />} bodyContent={<Results />} />;

The provided styles and layout can be found in the react-search-ui-views package.

Read the Customization guide for more details.

FAQ 🔮

Where can I learn more?

The Advanced README contains several useful guides. 😎

Is Search UI only for React?

Nope. Search UI is "headless".

You can write support for it into any JavaScript framework. You can even use vanilla JavaScript.

Read the Headless Core Guide for more information.

Can I build my own Components?

Yes! Absolutely.

Check out the Build Your Own Component Guide.

Does Search UI only work with App Search?

Nope! We do have two first party connectors: Site Search and App Search.

But Search UI is headless. You can use any search API.

Read the Connectors and Handlers Guide to learn more, or check out the Elasticsearch Example.

Where do I report issues with the Search UI?

If something is not working as expected, please open an issue.

Where can I go to get help?

Connect with the community and maintainers directly on Gitter.

If you are using an Elastic product as your connector, try the Elastic community...

Contribute 🚀

We welcome contributors to the project. Before you begin, a couple notes...

  • Read the Search UI Contributor's Guide.
  • Prior to opening a pull request, please:
    • Create an issue to discuss the scope of your proposal.
    • Sign the Contributor License Agreement. We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once.
  • Please write simple code and concise documentation, when appropriate.

License 📗

Apache-2.0 © Elastic

Thank you to all the contributors!

You can’t perform that action at this time.