Search Ui

2. Prerequisites

Before starting this guide, the developer should have:

1. A working Elasticsearch index with data (from any backend recipe)
2. Connection details — one of:
   • Cloud ID (Elastic Cloud Hosted)
   • Elasticsearch project endpoint URL (Elastic Cloud Serverless)
   • Host URL (self-managed)
3. An API key with at least read access to the index
4. A React project (or willingness to create one). Next.js is also supported with a dedicated integration pattern.

If they don't have a React project yet, scaffold one:

npx create-react-app my-search-app
cd my-search-app

Or with Next.js:

npx create-next-app@latest my-search-app
cd my-search-app

3. Installation

npm install @elastic/search-ui @elastic/react-search-ui @elastic/react-search-ui-views @elastic/search-ui-elasticsearch-connector

Three packages:

• @elastic/search-ui — headless core (state, actions, query orchestration)
• @elastic/react-search-ui — React bindings (SearchProvider, useSearch hook)
• @elastic/react-search-ui-views — pre-built React components with default styling
• @elastic/search-ui-elasticsearch-connector — connects to Elasticsearch directly

4. Connector Setup

The connector is how Search UI talks to Elasticsearch. Setup depends on the deployment model.

Development: Direct Connection

For local development and prototyping, connect directly. Never use this in production — it exposes API credentials to the browser.

Elastic Cloud Hosted:

import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";

const connector = new ElasticsearchAPIConnector({
  cloud: {
    id: "<your-cloud-id>"
  },
  index: "<your-index-name>",
  apiKey: "<read-only-api-key>"
});

Find your Cloud ID in the Elastic Cloud console under your deployment's details.

Elastic Cloud Serverless:

const connector = new ElasticsearchAPIConnector({
  host: "https://<your-project-id>.es.<region>.aws.elastic.cloud",
  index: "<your-index-name>",
  apiKey: "<read-only-api-key>"
});

Use the Elasticsearch endpoint from your Serverless project settings. Serverless projects use host (not cloud.id).

Self-managed:

const connector = new ElasticsearchAPIConnector({
  host: "http://localhost:9200",
  index: "<your-index-name>",
  apiKey: "<read-only-api-key>"
});

CORS for direct browser connections: If connecting directly from the browser (development only), Elasticsearch needs CORS headers. In Elastic Cloud Hosted, go to deployment settings → Edit user settings and add:

http.cors.allow-origin: "*"
http.cors.enabled: true
http.cors.allow-credentials: true
http.cors.allow-methods: OPTIONS, HEAD, GET, POST, PUT, DELETE
http.cors.allow-headers: X-Requested-With, X-Auth-Token, Content-Type, Content-Length, Authorization, Access-Control-Allow-Headers, Accept, x-elastic-client-meta

Serverless projects handle CORS automatically. Self-managed clusters need the same settings in elasticsearch.yml.

Production: Proxy Connector

In production, proxy all requests through your backend. This avoids exposing credentials, lets you add caching, logging, and access control.

Frontend (browser):

import { ApiProxyConnector } from "@elastic/search-ui-elasticsearch-connector/api-proxy";

const connector = new ApiProxyConnector({
  basePath: "/api"
});

Backend (Express server):

import express from "express";
import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";

const app = express();
app.use(express.json());

const connector = new ElasticsearchAPIConnector({
  host: "<your-elasticsearch-endpoint>",
  index: "<your-index-name>",
  apiKey: "<your-api-key>"
});

app.post("/api/search", async (req, res) => {
  const { state, queryConfig } = req.body;
  const response = await connector.onSearch(state, queryConfig);
  res.json(response);
});

app.post("/api/autocomplete", async (req, res) => {
  const { state, queryConfig } = req.body;
  const response = await connector.onAutocomplete(state, queryConfig);
  res.json(response);
});

app.listen(3001);

This pattern works identically for Hosted, Serverless, and self-managed — the only difference is how you configure the server-side connector (cloud.id vs host).

Next.js: API Routes

Next.js has built-in API routes, so you don't need a separate Express server.

Frontend connector (services/SearchConnector.js):

class SearchConnector {
  onResultClick() {}
  onAutocompleteResultClick() {}

  async onSearch(requestState, queryConfig) {
    const response = await fetch("/api/search", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ requestState, queryConfig })
    });
    return response.json();
  }

  async onAutocomplete(requestState, queryConfig) {
    const response = await fetch("/api/autocomplete", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ requestState, queryConfig })
    });
    return response.json();
  }
}

export default SearchConnector;

API routes (pages/api/search.js and pages/api/autocomplete.js):

import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";

const connector = new ElasticsearchAPIConnector({
  host: "<your-elasticsearch-endpoint>",
  index: "<your-index-name>",
  apiKey: "<your-api-key>"
});

export default async function handler(req, res) {
  const { requestState, queryConfig } = req.body;
  const response = await connector.onSearch(requestState, queryConfig);
  res.json(response);
}

5. Configuration

The configuration object tells Search UI which fields to search, which fields to show, and how to build facets. This must match the index mapping created in the backend recipe.

Mapping Config to Your Index

The configuration fields map directly to the Elasticsearch index mapping. Here's how to translate:

Example: Product Search Config

This matches the index mapping from the catalog-ecommerce recipe:

const config = {
  apiConnector: connector,
  alwaysSearchOnInitialLoad: true,
  searchQuery: {
    search_fields: {
      title: { weight: 3 },
      description: {},
      brand: { weight: 2 },
      tags: {}
    },
    result_fields: {
      title: { snippet: { size: 100, fallback: true } },
      description: { snippet: { size: 200, fallback: true } },
      brand: { raw: {} },
      price: { raw: {} },
      rating: { raw: {} },
      image_url: { raw: {} },
      category: { raw: {} }
    },
    fuzziness: true,
    disjunctiveFacets: ["category", "brand"],
    facets: {
      category: { type: "value", size: 20 },
      brand: { type: "value", size: 20 },
      price: {
        type: "range",
        ranges: [
          { from: 0, to: 25, name: "Under $25" },
          { from: 25, to: 50, name: "$25–$50" },
          { from: 50, to: 100, name: "$50–$100" },
          { from: 100, to: 200, name: "$100–$200" },
          { from: 200, name: "$200+" }
        ]
      },
      rating: {
        type: "range",
        ranges: [
          { from: 4, name: "4+ stars" },
          { from: 3, to: 4, name: "3–4 stars" },
          { from: 0, to: 3, name: "Under 3 stars" }
        ]
      }
    }
  },
  autocompleteQuery: {
    results: {
      resultsPerPage: 5,
      search_fields: {
        "title.autocomplete": { weight: 3 }
      },
      result_fields: {
        title: { snippet: { size: 100, fallback: true } },
        price: { raw: {} },
        image_url: { raw: {} }
      }
    },
    suggestions: {
      types: {
        documents: { fields: ["title_suggest"] }
      },
      size: 4
    }
  }
};

disjunctiveFacets — list fields here if you want facet counts to stay visible after a selection. Without this, selecting "Electronics" as a category would hide all other category options. With it, the user can see counts for other categories and add more selections.

fuzziness: true — enables typo tolerance. Internally maps to Elasticsearch's fuzziness: "AUTO".

Autocomplete Field Requirements

Autocomplete has two modes that require different field types in the mapping:

If the backend recipe already created completion or search_as_you_type fields, reference them here. If not, the developer will need to update the mapping and reindex.

6. Components

Minimal Working Search Page

import React from "react";
import {
  SearchProvider,
  SearchBox,
  Results,
  PagingInfo,
  ResultsPerPage,
  Paging,
  Facet,
  Sorting,
  ErrorBoundary
} from "@elastic/react-search-ui";
import { Layout } from "@elastic/react-search-ui-views";
import "@elastic/react-search-ui-views/lib/styles/styles.css";

export default function SearchPage() {
  return (
    <SearchProvider config={config}>
      <div className="App">
        <ErrorBoundary>
          <Layout
            header={
              <SearchBox
                autocompleteResults={{
                  titleField: "title",
                  urlField: "url",
                  sectionTitle: "Results"
                }}
                autocompleteSuggestions={true}
                debounceLength={300}
              />
            }
            sideContent={
              <div>
                <Facet field="category" label="Category" />
                <Facet field="brand" label="Brand" />
                <Facet field="price" label="Price" />
                <Facet field="rating" label="Rating" />
              </div>
            }
            bodyContent={<Results shouldTrackClickThrough />}
            bodyHeader={
              <>
                <PagingInfo />
                <ResultsPerPage options={[10, 20, 50]} />
                <Sorting
                  label="Sort by"
                  sortOptions={[
                    { name: "Relevance", value: [] },
                    { name: "Price: Low to High", value: [{ field: "price", direction: "asc" }] },
                    { name: "Price: High to Low", value: [{ field: "price", direction: "desc" }] },
                    { name: "Rating", value: [{ field: "rating", direction: "desc" }] }
                  ]}
                />
              </>
            }
            bodyFooter={<Paging />}
          />
        </ErrorBoundary>
      </div>
    </SearchProvider>
  );
}

Available Components

Customizing Result Display

Override the default result view to show product cards, images, or custom layouts:

<Results
  resultView={({ result }) => (
    <div className="product-card">
      {result.image_url?.raw && (
        <img src={result.image_url.raw} alt={result.title?.raw} />
      )}
      <h3 dangerouslySetInnerHTML={{ __html: result.title?.snippet || result.title?.raw }} />
      <p className="price">${result.price?.raw}</p>
      <p className="brand">{result.brand?.raw}</p>
      {result.rating?.raw && <span>{"★".repeat(Math.round(result.rating.raw))}</span>}
    </div>
  )}
/>

Styling

Search UI ships with default CSS. Import it to get a working layout immediately:

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

Override with your own CSS using the sui- class prefix (e.g., .sui-search-box, .sui-facet, .sui-result). Every component also accepts a className prop.

7. Custom Query Strategies

Search UI's default query works for keyword search. For semantic, hybrid, or advanced queries, use getQueryFn to override the query generation.

Semantic Search (requires ES 8.15+ with semantic_text field)

const connector = new ElasticsearchAPIConnector({
  // ... connection config ...
  getQueryFn: (state, config) => ({
    semantic: {
      field: "content_semantic",
      query: state.searchTerm
    }
  })
});

Hybrid Search (keyword + semantic via RRF)

For hybrid search, use interceptSearchRequest to inject a retriever-based query:

const connector = new ElasticsearchAPIConnector({
  // ... connection config ...
  interceptSearchRequest: async ({ requestBody, requestState, queryConfig }, next) => {
    if (!requestState.searchTerm) return next(requestBody);

    const modifiedBody = {
      ...requestBody,
      query: undefined,
      retriever: {
        rrf: {
          retrievers: [
            {
              standard: {
                query: {
                  multi_match: {
                    query: requestState.searchTerm,
                    fields: ["title^3", "description"]
                  }
                }
              }
            },
            {
              standard: {
                query: {
                  semantic: {
                    field: "content_semantic",
                    query: requestState.searchTerm
                  }
                }
              }
            }
          ]
        }
      }
    };

    return next(modifiedBody);
  }
});

Sparse Vector / ELSER

const connector = new ElasticsearchAPIConnector({
  // ... connection config ...
  getQueryFn: (state, config) => ({
    sparse_vector: {
      field: "content_embedding",
      inference_id: ".elser-2-elasticsearch",
      query: state.searchTerm
    }
  })
});

Version Considerations for Query Strategies

When generating code, check the developer's Elasticsearch version (confirmed in the main playbook's Step 3) and only recommend query strategies their version supports.

8. Known Limitations

• Nested objects don't render — Search UI's Elasticsearch connector cannot display nested object fields. Use flattened or keyword fields for facets instead of nested.
• React-only components — The pre-built components (@elastic/react-search-ui-views) are React-only. The headless core works with any framework, but you must build your own UI components.
• Query DSL only — Search UI generates Query DSL, not ES|QL. ES|QL is not supported for search queries through Search UI.
• No built-in auth — Search UI doesn't handle user authentication. If different users see different data (multi-tenancy), implement document-level security via the proxy layer.
• Facet counts with filters — Without disjunctiveFacets, selecting a facet value hides other options. Always list filterable facets in disjunctiveFacets for a good UX.

9. Common Follow-Ups

10. Connecting to Backend Recipes

This guide is designed to plug into any backend recipe. Here's how the handoff works:

The backend recipe builds the index, mapping, ingestion, and API. This recipe builds the frontend on top. If the developer followed a backend recipe that produced a Flask/Express API, they have two choices:

1. Use Search UI's connector to query Elasticsearch directly (through a proxy) — replaces the backend API for search
2. Keep the backend API and build a custom connector that calls it — useful when the API does more than search (auth, logging, business logic)

For option 2, implement a custom connector:

class CustomAPIConnector {
  async onSearch(requestState, queryConfig) {
    const response = await fetch("/api/search", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        query: requestState.searchTerm,
        filters: requestState.filters,
        page: requestState.current,
        size: requestState.resultsPerPage,
        sort: requestState.sortField
      })
    });
    const data = await response.json();
    // Transform your API response to Search UI's expected format
    return {
      results: data.hits.map(hit => ({ ...hit, id: { raw: hit.id } })),
      totalResults: data.total,
      facets: data.facets || {}
    };
  }

  async onAutocomplete(requestState, queryConfig) {
    // Similar implementation for autocomplete
  }

  onResultClick() {}
  onAutocompleteResultClick() {}
}

References

• Search UI documentation
• Elasticsearch Connector reference
• Production usage guide
• Next.js integration
• Component API reference
• CodeSandbox examples