-
-```
-
-### Properties
-
-| Name | Description |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| children | Content to show if no error has occurred, will be replaced with error messaging if there was an error. |
-| view | Used to override the default view for this Component. See for more information. |
diff --git a/docs/api-react-components-facet.mdx b/docs/api-react-components-facet.mdx
deleted file mode 100644
index ce9498193..000000000
--- a/docs/api-react-components-facet.mdx
+++ /dev/null
@@ -1,72 +0,0 @@
----
-id: api-react-components-facet
-slug: /search-ui/api/react/components/facet
-title: Facet
-date: 2022-02-27
-tags: ["facet"]
----
-
-Show a Facet filter for a particular field.
-
-Must configure the corresponding field in the `SearchProvider` object.
-
-### Example
-
-```jsx
-import { Facet } from "@elastic/react-search-ui";
-import { MultiCheckboxFacet } from "@elastic/react-search-ui-views";
-
-...
-
-
- {() => (
-
- )}
-
-```
-
-### Example of an OR based Facet filter
-
-Certain configuration of the `Facet` Component will require a "disjunctive" facet to work
-correctly. "Disjunctive" facets are facets that do not change when a selection is made. Meaning, all available options
-will remain as selectable options even after a selection is made.
-
-```jsx
-import { Facet } from "@elastic/react-search-ui";
-import { MultiCheckboxFacet } from "@elastic/react-search-ui-views";
-
-...
-
-
- {() => (
-
- )}
-
-```
-
-### Properties
-
-| Name | Description |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| field | Field name corresponding to this filter. This requires that the corresponding field has been configured in `facets` on the top level Provider. |
-| filterType | The type of filter to apply with the selected values. I.e., should "all" of the values match, or just "any" of the values, or "none" of the values. Note: See the example above which describes using "disjunctive" facets in conjunction with filterType. |
-| label | A static label to show in the facet filter. |
-| show | The number of facet filter options to show before concatenating with a "more" link. |
-| view | Used to override the default view for this Component. See for more information. |
-| isFilterable | Whether or not to show Facet quick filter. |
diff --git a/docs/api-react-components-paging-info.mdx b/docs/api-react-components-paging-info.mdx
deleted file mode 100644
index b86c587ff..000000000
--- a/docs/api-react-components-paging-info.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-id: api-react-components-paging-info
-slug: /search-ui/api/react/components/paging-info
-title: PagingInfo
-date: 2022-02-27
-tags: ["demo"]
----
-
-Paging details, like "1 - 20 of 100 results".
-
-### Example
-
-```jsx
-
-import { PagingInfo } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Properties
-
-| Name | Description |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| view | Used to override the default view for this Component. See for more information. |
diff --git a/docs/api-react-components-paging.mdx b/docs/api-react-components-paging.mdx
deleted file mode 100644
index 8bdf4ebfa..000000000
--- a/docs/api-react-components-paging.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-id: api-react-components-paging
-slug: /search-ui/api/react/components/paging
-title: Paging
-date: 2022-02-27
-tags: ["Paging"]
----
-
-Navigate through pagination.
-
-### Example
-
-```jsx
-
-import { Paging } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Properties
-
-| Name | Description |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| view | Used to override the default view for this Component. See for more information. |
diff --git a/docs/api-react-components-result.mdx b/docs/api-react-components-result.mdx
deleted file mode 100644
index 948f420d2..000000000
--- a/docs/api-react-components-result.mdx
+++ /dev/null
@@ -1,58 +0,0 @@
----
-id: api-react-components-result
-slug: /search-ui/api/react/components/result
-title: Result
-date: 2022-02-27
-tags: ["demo"]
----
-
-## Result
-
-Displays a search result.
-
-### Example
-
-```jsx
-
-import { Result } from "@elastic/react-search-ui";
-
-...
-
-
- {({ results }) => {
- return (
-
- {results.map(result => (
-
- ))}
-
- );
- }}
-
-```
-
-### Configuring search queries
-
-Certain aspects of search results can be configured in `SearchProvider`, using the `searchQuery` configuration, such as
-term highlighting and search fields. See the guide
-for more information.
-
-### Properties
-
-| Name | Description |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| titleField | Name of field to use as the title from each result. |
-| shouldTrackClickThrough | Whether or not to track a clickthrough event when clicked. |
-| clickThroughTags | Tags to send to analytics API when tracking clickthrough. |
-| urlField | Name of field to use as the href from each result. |
-| view | Used to override the default view for this Component. See for more information. |
-| result | Used to override the default view for this Component. See for more information. |
diff --git a/docs/api-react-components-results-per-page.mdx b/docs/api-react-components-results-per-page.mdx
deleted file mode 100644
index ee1080c9a..000000000
--- a/docs/api-react-components-results-per-page.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
----
-id: api-react-components-results-per-page
-slug: /search-ui/api/react/components/results-per-page
-title: ResultsPerPage
-date: 2022-02-27
-tags: ["demo"]
----
-
-Shows a dropdown for selecting the number of results to show per page.
-
-Uses [20, 40, 60] as default options. You can use `options` prop to pass custom options.
-
-**Note:** When passing custom options make sure one of the option values match
-the current `resultsPerPageProp` value, which is 20 by default.
-To override `resultsPerPage` default value, use the property.
-
-### Example
-
-```jsx
-
-import { ResultsPerPage } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Example using custom options
-
-```jsx
-
-import { SearchProvider, ResultsPerPage } from "@elastic/react-search-ui";
-
-
-
-
-```
-
-### Properties
-
-| Name | Description |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| options | Dropdown options to select the number of results to show per page. |
-| view | Used to override the default view for this Component. See for more information. |
diff --git a/docs/api-react-components-results.mdx b/docs/api-react-components-results.mdx
deleted file mode 100644
index acd8f7289..000000000
--- a/docs/api-react-components-results.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-id: api-react-components-results
-slug: /search-ui/api/react/components/results
-title: Results
-date: 2022-02-27
-tags: ["demo"]
----
-
-Displays all search results.
-
-### Example
-
-```jsx
-
-import { Results } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Example overriding Result view
-
-```jsx
- {
- return (
-
- );
- }}
-/>
-```
-
-for more examples on how to override the view, see .
-
-### Configuring search queries
-
-Certain aspects of search results can be configured in `SearchProvider`, using the `searchQuery` configuration, such as
-term highlighting and search fields. See the guide
-for more information.
-
-### Properties
-
-| Name | Description |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| resultView | Used to override individual Result views. See the Customizing Component views and html section for more information. |
-| titleField | Name of field to use as the title from each result. |
-| shouldTrackClickThrough | Whether or not to track a clickthrough event when clicked. |
-| clickThroughTags | Tags to send to analytics API when tracking clickthrough. |
-| urlField | Name of field to use as the href from each result. |
-| thumbnailField | Name of field to use for thumbnail image. Should be a valid URL and at least 220px wide. |
-| view | Used to override the default view for this Component. See for more information. |
diff --git a/docs/api-react-components-search-box.mdx b/docs/api-react-components-search-box.mdx
deleted file mode 100644
index 6f2cffa4e..000000000
--- a/docs/api-react-components-search-box.mdx
+++ /dev/null
@@ -1,292 +0,0 @@
----
-id: api-react-components-search-box
-slug: /search-ui/api/react/components/search-box
-title: SearchBox
-date: 2022-02-27
-tags: ["demo"]
----
-
-Input element which accepts search terms and triggers a new search query.
-
-### Example
-
-```jsx
-
-import { SearchBox } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Configuring search queries
-
-The input from `SearchBox` will be used to trigger a new search query. That query can be further customized
-in the `SearchProvider` configuration, using the `searchQuery` property. See the guide for more information.
-
-### Example of passing custom props to text input element
-
-```jsx
-
-```
-
-### Example of view customizations
-
-You can customize the entire view. This is useful to use an entirely different
-autocomplete library (we use [downshift](https://github.com/downshift-js/downshift)). But for making small
-customizations, like simply hiding the search button, this is often overkill.
-
-```jsx
- (
-
- )}
-/>
-```
-
-You can also just customize the input section of the search box. Useful for things
-like hiding the submit button or rearranging dom structure:
-
-```jsx
- (
- <>
-
-
- {getAutocomplete()}
-
-
-
- )}
-/>
-```
-
-Note that `getInputProps` and `getButtonProps` are
-[prop getters](https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters).
-They are meant return a props object to spread over their corresponding UI elements. This lets you arrange
-elements however you'd like in the DOM. It also lets you pass additional properties. You should pass properties
-through these functions, rather directly on elements, in order to not override base values. For instance,
-adding a `className` through these functions will assure that the className is only appended, not overriding base class values on those values.
-
-`getAutocomplete` is used to determine where the autocomplete dropdown will be shown.
-
-Or you can also just customize the autocomplete dropdown:
-
-```jsx
- (
-
- {autocompletedResults.map((result, i) => (
-
- Result {i}: {result.title.snippet}
-
- ))}
-
- )}
-/>
-```
-
-### Example using autocomplete results
-
-"Results" are search results. The default behavior for autocomplete
-results is to link the user directly to a result when selected, which is why
-a "titleField" and "urlField" are required for the default view.
-
-```jsx
-
-```
-
-### Example using autocomplete suggestions
-
-"Suggestions" are different than "results". Suggestions are suggested queries. Unlike an autocomplete result, a
-suggestion does not go straight to a result page when selected. It acts as a regular search query and
-refreshes the result set.
-
-```jsx
-
-```
-
-### Example using autocomplete suggestions and autocomplete results
-
-The default view will show both results and suggestions, divided into
-sections. Section titles can be added to help distinguish between the two.
-
-```jsx
-
-```
-
-### Configuring autocomplete queries
-
-Autocomplete queries can be customized in the `SearchProvider` configuration, using the `autocompleteQuery` property.
-See the for more information.
-
-```jsx
-
-
-
-```
-
-### Example using multiple types of autocomplete suggestions
-
-"Suggestions" can be generated via multiple methods. They can be derived from
-common terms and phrases inside of documents, or be "popular" queries
-generated from actual search queries made by users. This will differ
-depending on the particular Search API you are using.
-
-**Note**: Elastic App Search currently only supports type "documents", and Elastic Site Search and Workplace Search
-do not support suggestions. This is purely illustrative in case a Connector is used that
-does support multiple types.
-
-```jsx
-
-
-
-```
-
-### Example using autocomplete in a site header
-
-This is an example from a [Gatsby](https://www.gatsbyjs.org/) site, which overrides "submit" to navigate a user to the search
-page for suggestions, and maintaining the default behavior when selecting a result.
-
-```jsx
- {
- navigate("/search?q=" + searchTerm);
- }}
- onSelectAutocomplete={(selection, {}, defaultOnSelectAutocomplete) => {
- if (selection.suggestion) {
- navigate("/search?q=" + selection.suggestion);
- } else {
- defaultOnSelectAutocomplete(selection);
- }
- }}
-/>
-```
-
-### Properties
-
-| Name | Description |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| className | |
-| shouldClearFilters | Should existing filters be cleared when a new search is performed? |
-| inputProps | Props for underlying 'input' element. I.e., `{ placeholder: "Enter Text"}`. |
-| searchAsYouType | Executes a new search query with every key stroke. You can fine tune the number of queries made by adjusting the `debounceLength` parameter. |
-| debounceLength | When using `searchAsYouType`, it can be useful to "debounce" search requests to avoid creating an excessive number of requests. This controls the length to debounce / wait. |
-| view | Used to override the default view for this Component. See the section for more information. |
-| autocompleteResults | Configure and autocomplete search results. Boolean option is primarily available for implementing custom views. |
-| autocompleteSuggestions | Configure and autocomplete query suggestions. Boolean option is primarily available for implementing custom views. Configuration may or may not be keyed by "Suggestion Type", as APIs for suggestions may support may than 1 type of suggestion. If it is not keyed by Suggestion Type, then the configuration will be applied to the first type available. |
-| autocompleteMinimumCharacters | Minimum number of characters before autocompleting. |
-| autocompleteView | Provide a different view just for the autocomplete dropdown. |
-| inputView | Provide a different view just for the input section. |
-| onSelectAutocomplete | Allows overriding behavior when selected, to avoid creating an entirely new view. In addition to the current `selection`, various helpers are passed as `options` to the second parameter. This third parameter is the default `onSelectAutocomplete`, which allows you to defer to the original behavior. |
-| onSubmit | Allows overriding behavior when submitted. Receives the search term from the search box. |
-
-#### AutocompleteResultsOptions
-
-| Name | Description |
-| ----------------------- | --------------------------------------------------------- |
-| linkTarget | Used to open links in a new tab. |
-| sectionTitle | Title to show in section within dropdown. |
-| shouldTrackClickThrough | Only applies to Results, not Suggestions. |
-| clickThroughTags | Tags to send to analytics API when tracking clickthrough. |
-| titleField | Field within a Result to use as the "title". |
-| urlField | Field within a Result to use for linking. |
-
-#### AutocompleteSuggestionsOptions
-
-| Name | Description |
-| ------------ | ---------------------------------------- |
-| sectionTitle | Title to show in section within dropdown |
diff --git a/docs/api-react-components-sorting.mdx b/docs/api-react-components-sorting.mdx
deleted file mode 100644
index 13f7aec8b..000000000
--- a/docs/api-react-components-sorting.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: api-react-components-sorting
-slug: /search-ui/api/react/components/sorting
-title: Sorting
-date: 2022-02-27
-tags: ["demo"]
----
-
-Shows a dropdown for selecting the current Sort.
-
-### Example
-
-```jsx
-
-import { Sorting } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Properties
-
-| Name | Description |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | |
-| label | A static label to show in the Sorting Component. |
-| sortOptions | |
-| view | Used to override the default view for this Component. See for more information. |
diff --git a/docs/api-react-core.mdx b/docs/api-react-core.mdx
deleted file mode 100644
index 03f0da528..000000000
--- a/docs/api-react-core.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-id: api-react-core
-slug: /search-ui/api/react/core
-title: Integration
-date: 2022-03-31
-tags: ["core"]
----
-
-The `SearchProvider` is a React wrapper around the Headless Core, and makes state and actions available to Search UI
-and in a React [Context](https://reactjs.org/docs/context.html), and also via a
-[Render Prop](https://reactjs.org/docs/render-props.html).
-
-It looks like this:
-
-```jsx
-import { SearchProvider, SearchBox } from "@elastic/react-search-ui";
-import AppSearchAPIConnector from "@elastic/search-ui-app-search-connector";
-
-const connector = new AppSearchAPIConnector({
- searchKey: "search-371auk61r2bwqtdzocdgutmg",
- engineName: "search-ui-examples",
- endpointBase: "http://my-app-search-host:3002"
-});
-
-const configurationOptions = {
- apiConnector: connector,
- searchQuery: { ... },
- autocompleteQuery: { ... },
- hasA11yNotifications: true,
- a11yNotificationMessages: {
- searchResults: ({ start, end, totalResults, searchTerm }) =>
- `Searching for "${searchTerm}". Showing ${start} to ${end} results out of ${totalResults}.`
- },
- alwaysSearchOnInitialLoad: true
-};
-
-const App = () => (
-
-
-
-
-
-);
-```
-
-| option | type | description |
-| --------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `apiConnector` | APIConnector | Instance of a Connector. See Connectors API section. |
-| `onSearch` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Handlers](#handlers) for more information. |
-| `onAutocomplete` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Handlers](#handlers) for more information. |
-| `onResultClick` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Handlers](#handlers) for more information. |
-| `onAutocompleteResultClick` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Handlers](#handlers) for more information. |
-| `autocompleteQuery` | [Autocomplete Query Config](/api/configuration#autocomplete-query) | Configuration options for the autocomplete query. |
-| `debug` | Boolean | Trace log actions and state changes. Default is false. |
-| `initialState` | Object | Set inital state of Search UI. See [Initial State](#initial-state) for more information. |
-| `searchQuery` | [Search Query Config](/api/configuration#search-query-queryconfig) | Configuration options for the main search query. |
-| `trackUrlState` | Boolean | By default, [Request State](#request-state) will be synced with the browser url. To turn this off, pass `false`. |
-| `urlPushDebounceLength` | Integer | The amount of time in milliseconds to debounce/delay updating the browser url after the UI update. This, for example, prevents excessive history entries while a user is still typing in a live search box. Default is 500. |
-| `hasA11yNotifications` | Boolean | Search UI will create a visually hidden live region to announce search results & other actions to screen reader users. This accessibility feature will be turned on by default in our 2.0 release. Default is false. |
-| `a11yNotificationMessages` | Object | You can override our default screen reader [messages](packages/search-ui/src/A11yNotifications.js#L49) (e.g. for localization), or create your own custom notification, by passing in your own key and message function(s). |
-| `alwaysSearchOnInitialLoad` | Boolean | If true, Search UI will always do an initial search, even when no inital Request State is set. |
-
-### Context
-
-The "Context" is a flattened object containing, as keys, all and .
-
-We refer to it as "Context" because it is implemented with a [React Context](https://reactjs.org/docs/context.html).
-
-ex.
-
-```js
-{
- resultsPerPage: 10, // Request State
- setResultsPerPage: () => {}, // Action
- current: 1, // Request State
- setCurrent: () => {}, // Action
- error: '', // Response State
- isLoading: false, // Response State
- totalResults: 1000, // Response State
- ...
-}
-```
-
-### Initial State
-
-This is useful for defaulting a search term, sort, etc.
-
-Example
-
-```js
- initialState: { searchTerm: "test", resultsPerPage: 40 }
-```
-
-See for more properties that can be set in initial state.
diff --git a/docs/connectors-api-elasticsearch.mdx b/docs/connectors-api-elasticsearch.mdx
deleted file mode 100644
index 0830ecd1c..000000000
--- a/docs/connectors-api-elasticsearch.mdx
+++ /dev/null
@@ -1,210 +0,0 @@
----
-id: connectors-api-elasticsearch
-slug: /search-ui/connectors-api/elasticsearch-connector
-title: Elasticsearch Connector
-date: 2022-04-13
-tags: ["demo"]
----
-
-
- Elasticsearch connector for Search UI is currently in technical preview
- status. It is not ready for production use.
-
-
-Search UI provides a way to connect to Elasticsearch directly without needing Enterprise Search. This is useful for when you dont need the features of Enterprise Search, such as relevance tuning.
-
-The connector uses the same Search UI configuration that other connectors use.
-
-```js
-import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";
-
-const connector = new ElasticsearchAPIConnector({
- host: "http://localhost:9200", // host url for the Elasticsearch instance
- index: "", // index name where the search documents are contained
- apiKey: "" // Optional. apiKey used to authorize a connection to Elasticsearch instance.
- // This key will be visible to everyone so ensure its setup with restricted privileges.
- // See Authentication section for more details.
-});
-```
-
-| Param | Description |
-| ------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| host | Required. String type. The host url to the Elasticsearch instance |
-| index | Required. String type. The search index name |
-| apiKey | Optional. a credential used to access the Elasticsearch instance. See [Connection & Authentication](#connection-&-authentication) |
-
-## Connection & Authentication
-
-
- This connector will talk to the Elasticsearch instance directly from the
- browser. We **strongly** suggest you take additional steps to keep your
- Elasticsearch instance as secure as possible.
-
-
-You have the following options available to you for securely exposing your Elasticsearch instance to the internet:
-
-### Proxy the \_search API call through your API
-
-This envolves building an API route that will proxy the Elasticsearch call through your API. During the proxy, you are able to:
-
-- Ability to add any additional authentication headers / keys as you proxy the request through the API and to Elasticsearch.
-- Update the Elasticsearch query request to add any filters to filter restricted documents
-- Application performance monitoring of functionality
-- Your own user based authentication for your API
-- Add a caching layer between the API and Elasticsearch
-
-The connector will perform a `_search` query and will derive the endpoint path with the host and index. With `http://localhost:9200` host and `search-ui-example` index, the endpoint path will be `http://localhost:9200/search-ui-example/_search`. The connector will make a POST call with the elasticsearch query in the body of the request. To proxy the request through your API, you need to implement a route and update the connector's settings to use the proxy route.
-
-### Use an Elasticsearch api-key
-
-You can restrict access to indices by using an API key. We recommend you create an apiKey that is restricted to the particular index and has read-only authorization. See [Kibana API keys guide](https://www.elastic.co/guide/en/kibana/master/api-keys.html). To use the API key, place it within the Elasticsearch connection configuration.
-
-## Autocomplete
-
-Search UI supports autocomplete functionality to suggest search terms that provide results. The autocomplete functionality is built on top of the Elasticsearch `suggest` and `bool prefix query` API.
-
-To take advantage of the feature, first update the configuration.
-
-Below is an example of what the `autocompleteQuery` may look like.
-
-```js
-autocompleteQuery: {
- // performs a prefix search on the query
- results: {
- resultsPerPage: 5, // number of results to display. Default is 5.
- search_fields: {
- // the fields to prefix search on
- title_suggest: {}
- },
- result_fields: {
- // Add snippet highlighting within autocomplete suggestions
- title: { snippet: { size: 100, fallback: true }},
- nps_link: { raw: {} }
- }
- },
- // performs a query to suggest for values that partially match the incomplete query
- suggestions: {
- types: {
- // Limit query to only suggest based on "title" field
- documents: { fields: ["title_completion"] }
- },
- // Limit the number of suggestions returned from the server
- size: 4
- }
-}
-
-```
-
-Above we are configuring both the `results` and `suggestions` sections of the autocomplete query.
-
-`results` will need a search field to perform a prefix search on the query. We advise using a `search_as_you_type` field to be used.
-`suggestions` require a `completion` type field to perform a query to suggest for values that partially match the incomplete query.
-
-Below is an example of the mappings for the above example. `title_suggest` is a `search_as_you_type` field and `title_completion` is a `completion` type field.
-
-```json
-{
- "mappings": {
- "properties": {
- "title_suggest": {
- "type": "search_as_you_type"
- },
- "title_completion": {
- "type": "completion"
- }
- }
- }
-}
-```
-
-With a combination of this configuration + the component with autocomplete configuration, your users will be able to see suggestions as they type within the search box.
-
-## Node.js Integration
-
-The Elasticsearch API Connector builds the Elasticsearch query and performs the request directly to Elasticsearch from the browser. Depending on what you're building, you may want this logic to be done on the server and provide your clients a simplified API.
-
-First step is to implement two routes to handle `search` and `autocomplete` requests. In example below, we are using express.js framework to implement these http routes within node.js.
-
-```js
-// index.js
-
-var express = require("express");
-var APIConnector =
- require("@elastic/search-ui-elasticsearch-connector").default;
-require("cross-fetch/polyfill");
-
-var app = express();
-
-app.use(express.json());
-app.use(express.urlencoded({ extended: false }));
-
-const connector = new APIConnector({
- host: "http://localhost:9200", // host url for the Elasticsearch instance
- index: "search-ui-examples", // index name where the search documents are contained
- apiKey: "apiKeyExample" // Optional. apiKey used to authorize a connection to Elasticsearch instance.
-});
-
-app.post("/search", async (req, res) => {
- const { query, options } = req.body;
- const response = await connector.onSearch(query, options);
- res.json(response);
-});
-
-app.post("/autocomplete", async (req, res) => {
- const { query, options } = req.body;
- const response = await connector.onAutocomplete(query, options);
- res.json(response);
-});
-
-var listener = app.listen(8080, function () {
- console.log("Listening on port " + listener.address().port);
-});
-```
-
-Next, you can add a simple connector which passes the configuration and query from the client to the server.
-
-```js
-class CustomConnector {
- constructor(host) {
- this.host = host;
- }
-
- async onSearch(query, options) {
- const response = await fetch(this.host + "/search", {
- method: "POST",
- headers: {
- "Content-Type": "application/json"
- },
- body: JSON.stringify({
- query,
- options
- })
- });
- return response.json();
- }
-
- async onAutocomplete(query, options) {
- const response = await fetch(this.host + "/autocomplete", {
- method: "POST",
- headers: {
- "Content-Type": "application/json"
- },
- body: JSON.stringify({
- query,
- options
- })
- });
- return response.json();
- }
-}
-
-const connector = new CustomConnector("https://my-api-host/");
-
-const config = {
- alwaysSearchOnInitialLoad: true,
- apiConnector: connector
- // ... typical search-ui configuration
-};
-```
-
-Thats it!. You should see the `CustomConnector` executing requests to the server, providing the search state and configuration in the body. The node.js server will use the Elasticsearch connector to perform a search to Elasticsearch and return the results back to the client.
diff --git a/docs/docset.yml b/docs/docset.yml
new file mode 100644
index 000000000..3543da598
--- /dev/null
+++ b/docs/docset.yml
@@ -0,0 +1,11 @@
+project: "Search UI docs"
+products:
+ - id: search-ui
+exclude:
+ - README.md
+cross_links:
+ - apm-agent-rum-js
+ - docs-content
+ - elasticsearch
+toc:
+ - toc: reference
diff --git a/docs/examples-search-as-you-type.mdx b/docs/examples-search-as-you-type.mdx
deleted file mode 100644
index a7d319a22..000000000
--- a/docs/examples-search-as-you-type.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
----
-id: examples-search-as-you-type
-slug: /search-ui/examples/search-as-you-type
-title: Search-as-you-type
-date: 2022-05-05
-tags: ["search-as-you-type"]
----
-
-Usually, the search query is executed when the user presses the enter key or clicks the search button.
-
-Search-as-you-type feature allows search queries to be executed on every keystroke.
-
-To implement this in Search UI, you'll need to add a `searchAsYouType={true}` prop to `` component.
-
-It's a good idea to add a debounce time — the Search UI will wait for users to finish typing before issuing the request. You can do it by adding a `debounceLength={300}` prop to `` component.
-
-See the example implementation below.
-
-
-
-Related documentation:
-
--
diff --git a/docs/examples-search-bar-in-header.mdx b/docs/examples-search-bar-in-header.mdx
deleted file mode 100644
index 6e021815a..000000000
--- a/docs/examples-search-bar-in-header.mdx
+++ /dev/null
@@ -1,41 +0,0 @@
----
-id: examples-search-bar-in-header
-slug: /search-ui/examples/search-bar-in-header
-title: Search bar in header
-date: 2022-05-11
-tags: ["search-bar-in-header"]
----
-
-It's a common pattern to have a search bar in the header of your website.
-Submitting a query in this search bar usually redirects user to a separate search results page.
-
-To implement this with Search UI use the `` component and add `onSubmit` prop that redirects user to the search page:
-
-```js
- {
- window.location.href = `${PATH_TO_YOUR_SEARCH_PAGE}?q=${searchTerm}`;
- }}
-/>
-```
-
-Once the redirect happens, Search UI will pick up the query from the URL and display the results.
-
-Check out the example implementation below.
-
-
-
-Related documentation:
-
--
diff --git a/docs/guides-customizing-styles-and-html.mdx b/docs/guides-customizing-styles-and-html.mdx
deleted file mode 100644
index e98db3252..000000000
--- a/docs/guides-customizing-styles-and-html.mdx
+++ /dev/null
@@ -1,170 +0,0 @@
----
-id: guides-customizing-styles-and-html
-slug: /search-ui/guides/customizing-styles-and-html
-title: Customizing Styles and HTML
-date: 2022-02-27
-tags: ["demo"]
----
-
-In this guide we'll customize some styles of the Search UI, modify the default HTML of one of the Search UI components, and also create a completely new Result component.
-
-Check out the live example below to see all the code in action.
-
-
-
-## Customizing styles
-
-We provide a default stylesheet to get your project started quickly.
-
-```jsx
-import "@elastic/react-search-ui-views/lib/styles/styles.css";
-```
-
-You could choose to add your own stylesheet to override or augment these styles:
-
-```jsx
-import "@elastic/react-search-ui-views/lib/styles/styles.css";
-import "your-custom-styles.css";
-```
-
-You could also choose to replace these styles completely with your own stylesheet:
-
-```jsx
-import "your-custom-styles.css";
-```
-
-When target styles to override, we generally advise that you rely only on styles that are prefixed with `.sui`. We try to keep these compatible for version upgrades so that we don't break your custom styles. However, we do recommend that you test your styles thoroughly when upgrading versions, even within minors.
-
-Here is an example of a simple stylesheet that overrides much of the blue in the base styles with red to create a simple red theme:
-
-```css
-.sui-search-box__submit {
- background: none;
- background-color: red;
-}
-
-.sui-layout-sidebar-toggle {
- color: red;
- border: 1px solid red;
-}
-
-.sui-result__title,
-.sui-result__title-link {
- color: red;
-}
-
-.sui-facet-view-more {
- color: red;
-}
-```
-
-## Customizing html
-
-All components in this library can be customized by providing a `view` prop.
-
-The view prop can be used to customize a component's look and feel while still maintaining the component's logic.
-
-This follows the [React Render Props](https://reactjs.org/docs/render-props.html) pattern. The `view` prop is a function. The various
-logic and values your view needs are passed through as parameters to the `view` function you provide.
-
-Every component will have a different function signature for its view.
-
-Here is an example of a custom view being provided for the `PagingInfo` component:
-
-```jsx
- (
-
-
- {start} - {end}
-
-
- )}
-/>
-```
-
-You'll note that the `view` function here has four parameters that are available to use:
-
-2. `searchTerm` - The search term used for this query.
-3. `start` - The number of the first result shown.
-4. `end` - The number of the last result shown.
-5. `totalResults` - The total number of results for this query.
-
-In this case, we've decided to create a simple view that shows the starting and ending result numbers on this page. We've chosen not to use
-the `totalResults` or `searchTerm` properties.
-
-## Common customizations
-
-### Results component
-
-Note that you can override the entire list of results in the `Results` component using the `view` propety or you can just override individual
-result views with the `resultView` prop.
-
-```jsx
-const CustomResultView = ({
- result,
- onClickLink
-}: {
- result: SearchResult;
- onClickLink: () => void;
-}) => (
-
+
+```
+
+## Properties [api-react-components-error-boundary-properties]
+
+| Name | Description |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| className | |
+| children | Content to show if no error has occurred, will be replaced with error messaging if there was an error. |
+| view | Used to override the default view for this Component. See [View customization](#api-react-components-error-boundary-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View |
+
+## View customization [api-react-components-error-boundary-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+The following properties are available in the view:
+
+| Name | Description |
+| --------- | ------------------------------------------------------------------------------------------------------ |
+| className | Passed through from main component. |
+| children | Content to show if no error has occurred, will be replaced with error messaging if there was an error. |
+| error | Type: `string`. The error message to show if an error occurred. |
+
+See [ErrorBoundary.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/ErrorBoundary.tsx) for an example.
diff --git a/docs/reference/api-react-components-facet.md b/docs/reference/api-react-components-facet.md
new file mode 100644
index 000000000..f235c5282
--- /dev/null
+++ b/docs/reference/api-react-components-facet.md
@@ -0,0 +1,120 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-facet.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Facet [api-react-components-facet]
+
+Show a Facet filter for a particular field.
+
+Must configure the corresponding field in the `SearchProvider` [facets](/reference/api-core-configuration.md#api-core-configuration-facets) object.
+
+## Example [api-react-components-facet-example]
+
+```jsx
+import { Facet } from "@elastic/react-search-ui";
+import { MultiCheckboxFacet } from "@elastic/react-search-ui-views";
+
+...
+
+
+ {() => (
+
+ )}
+
+```
+
+## Example of an OR based Facet filter [api-react-components-facet-example-of-an-or-based-facet-filter]
+
+Certain configuration of the `Facet` Component will require a "disjunctive" facet to work correctly. "Disjunctive" facets are facets that do not change when a selection is made. Meaning, all available options will remain as selectable options even after a selection is made.
+
+```jsx
+import { Facet } from "@elastic/react-search-ui";
+import { MultiCheckboxFacet } from "@elastic/react-search-ui-views";
+
+...
+
+
+ {() => (
+
+ )}
+
+```
+
+## Properties [api-react-components-facet-properties]
+
+| Name | Description |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className` | |
+| `field` | Field name corresponding to this filter. This requires that the corresponding field has been configured in `facets` on the top level Provider. |
+| `filterType` | The type of filter to apply with the selected values. I.e., should "all" of the values match, or just "any" of the values, or "none" of the values. Note: See the example above which describes using "disjunctive" facets in conjunction with filterType. |
+| `label` | A static label to show in the facet filter. |
+| `show` | The number of facet filter options to show before concatenating with a "Show more" link. |
+| `isFilterable` | Whether or not to show Facet quick filter. |
+| `persistent` | Whether the facet filter should persist across searches. When true, the facet filter will not be cleared when a new search is performed. |
+| `view` | Used to override the default view for this Component. See [View customization](#api-react-components-facet-view-customization) below. |
+| `*` | Any other property passed will be passed through and available to use in a Custom View |
+
+## View customization [api-react-components-facet-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+The following properties are available in the view:
+
+| Name | Description |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className` | Passed through from main component. |
+| `label` | Type: `string`. Passed through from main component. |
+| `onMoreClick` | Type: `() => void`. Used for a "Show more" link. Call this to show more options. |
+| `onRemove` | Type: `(value: FieldValue) => void`. Call this when a user removes a facet filter selection. Pass the `value` from the corresponding selection from `options`. |
+| `onChange` | Type: `(value: FieldValue) => void`. Call this when a user changes a facet filter selection. Pass the `value` from the corresponding selection from `options`. |
+| `onSelect` | Type: `(value: FieldValue) => void`. Call this when a user adds a facet filter selection. Pass the `value` from the corresponding selection from `options`. |
+| `options` | Type: `FacetValue[]`. The options to show available for selection for this facet. `selected` property will be true if this values is selected. |
+| `showMore` | Type: `boolean`. Whether or not to show a "Show more" link. If there are no more options available to show, then this will be `false`. |
+| `values` | Type: `FilterValue[]`. A list of all the selected values. This can also be deduced be inspected the `selected` properties of the `options`. |
+| `showSearch` | Type: `boolean`. Whether or not the compopnent is `isFilterable`. This would indicates that a filter search box should be shown. |
+| `onSearch` | Type: `(value: string) => void`. Call this to filter down the facet options shown. Used if there is a search box shown in relation to `showSearch`. |
+| `searchPlaceholder` | Type: `string`. The placeholder fo show in the filter search box when `showSearch` is true. |
+
+See [MultiCheckboxFacet.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/MultiCheckboxFacet.tsx) for an example.
+
+When overriding Facet views, note that there are pre-built options that you can choose from, in addition to providing your own:
+
+```jsx
+import {
+ BooleanFacet,
+ SingleSelectFacet,
+ SingleLinksFacet
+} from "@elastic/react-search-ui-views";
+
+// Default out-of-the-box view
+
+
+// Choose an alternate out-of-the-box view
+
+```
diff --git a/docs/reference/api-react-components-paging-info.md b/docs/reference/api-react-components-paging-info.md
new file mode 100644
index 000000000..8ae225064
--- /dev/null
+++ b/docs/reference/api-react-components-paging-info.md
@@ -0,0 +1,45 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-paging-info.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# PagingInfo [api-react-components-paging-info]
+
+Paging details, like "1 - 20 of 100 results".
+
+## Example [api-react-components-paging-info-example]
+
+```jsx
+import { PagingInfo } from "@elastic/react-search-ui";
+
+...
+
+
+```
+
+## Properties [api-react-components-paging-info-properties]
+
+| Name | Description |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| className | |
+| view | Used to override the default view for this Component. See [View customization](#api-react-components-paging-info-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View |
+
+## View customization [api-react-components-paging-info-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+The following properties are available in the view:
+
+| Name | Description |
+| ------------ | ------------------------------------------------------------------------------- |
+| className | Passed through from main component. |
+| end | Type: `number`. The position of the last result shown on this page of reuslts. |
+| searchTerm | Type: `string`. The current search term. |
+| start | Type: `number`. The position of the first result shown on this page of reuslts. |
+| totalResults | Type: `number`. The total number of results. |
+
+See [PagingInfo.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/PagingInfo.tsx) for an example.
diff --git a/docs/reference/api-react-components-paging.md b/docs/reference/api-react-components-paging.md
new file mode 100644
index 000000000..ab0cb875e
--- /dev/null
+++ b/docs/reference/api-react-components-paging.md
@@ -0,0 +1,45 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-paging.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Paging [api-react-components-paging]
+
+Navigate through pagination.
+
+## Example [api-react-components-paging-example]
+
+```jsx
+import { Paging } from "@elastic/react-search-ui";
+
+...
+
+
+```
+
+## Properties [api-react-components-paging-properties]
+
+| Name | Description |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| className | |
+| view | Used to override the default view for this Component. See [View customization](#api-react-components-paging-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View |
+
+## View customization [api-react-components-paging-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+The following properties are available in the view:
+
+| Name | Description |
+| -------------- | ----------------------------------------------------------------------- |
+| className | Passed through from main component. |
+| current | Type: `number`. The current page |
+| resultsPerPage | Type: `number`. The number of results that are shown per page. |
+| onChange | function(value: number) - call this with the newly selected page number |
+| totalPages | Type: `number`. The total number of pages. |
+
+See [Paging.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/Paging.tsx) for an example.
diff --git a/docs/reference/api-react-components-result.md b/docs/reference/api-react-components-result.md
new file mode 100644
index 000000000..a541da8f0
--- /dev/null
+++ b/docs/reference/api-react-components-result.md
@@ -0,0 +1,107 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-result.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Result [api-react-components-result]
+
+## Result [api-react-components-result-result]
+
+Displays a search result.
+
+### Example [api-react-components-result-example]
+
+```jsx
+import { Result } from "@elastic/react-search-ui";
+
+...
+
+
+ {({ results }) => {
+ return (
+
+ {results.map(result => (
+
+ ))}
+
+ );
+ }}
+
+```
+
+### Configuring search queries [api-react-components-result-configuring-search-queries]
+
+Certain aspects of search results can be configured in `SearchProvider`, using the `searchQuery` configuration, such as term highlighting and search fields. See the [Search Query Configuration](/reference/api-core-configuration.md#api-core-configuration-search-query-queryconfig) guide for more information.
+
+### Properties [api-react-components-result-properties]
+
+| Name | Description |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| className | |
+| titleField | Name of field to use as the title from each result. |
+| shouldTrackClickThrough | Whether or not to track a clickthrough event when clicked. |
+| clickThroughTags | Tags to send to analytics API when tracking clickthrough. |
+| urlField | Name of field to use as the href from each result. |
+| result | Type: `SearchResult`. An object representing the search result to render. |
+| view | Used to override the default view for this Component. See [View customization](#api-react-components-result-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View |
+
+### View customization [api-react-components-result-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+Example:
+
+```jsx
+const CustomResultView = ({
+ result,
+ onClickLink
+}: {
+ result: SearchResult,
+ onClickLink: () => void
+}) => (
+
+ {/* use 'raw' values of fields to access values without snippets */}
+
+
+
+ {/* Use the 'snippet' property of fields with dangerouslySetInnerHtml to render snippets */}
+
+
+
+);
+
+;
+```
+
+The following properties are available in the view:
+
+| Name | Description |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| className | Passed through from main component. |
+| result | Type: `SearchResult`. An object representing the search result to render. |
+| onClickLink | function() - Call this when a link is clicked to trigger click tracking. Only triggered if `shouldTrackClickThrough` was set to true on the main component. |
+| titleField | Passed through from main component. Not usually needed for custom views. |
+| urlField | Passed through from main component. Not usually needed for custom views. |
+| thumbnailField | Passed through from main component. Not usually needed for custom views. |
+
+See [Result.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/Result.tsx) for an example.
diff --git a/docs/reference/api-react-components-results-per-page.md b/docs/reference/api-react-components-results-per-page.md
new file mode 100644
index 000000000..f63faf629
--- /dev/null
+++ b/docs/reference/api-react-components-results-per-page.md
@@ -0,0 +1,68 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-results-per-page.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# ResultsPerPage [api-react-components-results-per-page]
+
+Shows a dropdown for selecting the number of results to show per page.
+
+Uses [20, 40, 60] as default options. You can use `options` prop to pass custom options.
+
+:::{note}
+When passing custom options make sure one of the option values match the current `resultsPerPageProp` value, which is 20 by default. To override `resultsPerPage` default value, use the [initial state](/reference/api-react-search-provider.md#api-react-search-provider-initial-state) property.
+:::
+
+## Example [api-react-components-results-per-page-example]
+
+```jsx
+import { ResultsPerPage } from "@elastic/react-search-ui";
+
+...
+
+
+```
+
+## Example using custom options [api-react-components-results-per-page-example-using-custom-options]
+
+```jsx
+import { SearchProvider, ResultsPerPage } from "@elastic/react-search-ui";
+
+
+
+
+```
+
+## Properties [api-react-components-results-per-page-properties]
+
+| Name | Description |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| className | |
+| options | Type: `number[]`. Dropdown options to select the number of results to show per page. |
+| view | Used to override the default view for this Component. See [View customization](#api-react-components-results-per-page-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View. |
+
+## View customization [api-react-components-results-per-page-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+The following properties are available in the view:
+
+| Name | Description |
+| --------- | -------------------------------------------------------------------------------------------------------------------- |
+| className | Passed through from main component. |
+| onChange | function(value: number) - Call this function with the select value from `options` after a user has made a selection. |
+| options | Passed through from main component. |
+| value | The currently selected option. |
+
+See [ResultsPerPage.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/ResultsPerPage.tsx) for an example.
diff --git a/docs/reference/api-react-components-results.md b/docs/reference/api-react-components-results.md
new file mode 100644
index 000000000..c013d2758
--- /dev/null
+++ b/docs/reference/api-react-components-results.md
@@ -0,0 +1,56 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-results.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Results [api-react-components-results]
+
+Displays all search results.
+
+## Example [api-react-components-results-example]
+
+```jsx
+import { Results } from "@elastic/react-search-ui";
+
+...
+
+
+```
+
+## Configuring search queries [api-react-components-results-configuring-search-queries]
+
+Certain aspects of search results can be configured in `SearchProvider`, using the `searchQuery` configuration, such as term highlighting and search fields. See the [Search Query Configuration](/reference/api-core-configuration.md#api-core-configuration-search-query-queryconfig) guide for more information.
+
+## Properties [api-react-components-results-properties]
+
+| Name | Description |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| className | |
+| titleField | Name of field to use as the title from each result. |
+| shouldTrackClickThrough | Whether or not to track a clickthrough event when clicked. |
+| clickThroughTags | Tags to send to analytics API when tracking clickthrough. |
+| urlField | Name of field to use as the href from each result. |
+| thumbnailField | Name of field to use for thumbnail image. Should be a valid URL and at least 220px wide. |
+| resultView | See [Result component customization.](/reference/api-react-components-result.md#api-react-components-result-view-customization) |
+| view | Used to override the default view for this Component. See [View customization](#api-react-components-results-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View |
+
+## View customization [api-react-components-results-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+This component accepts two view props: `view` and `resultView`. The `resultView` allows you to customize the individual result items that are displayed. The `view` prop allows you to customize that wrapper around those results, which by default is simply a `ul` element.
+
+A separate guide specifically for customizing the Result component can be found [here.](/reference/api-react-components-result.md#api-react-components-result-view-customization), which can be used for providing a `resultView` prop.
+
+The following properties are available in the view:
+
+| Name | Description |
+| --------- | ---------------------------------- |
+| className | Passed through from main component |
+| children | |
+
+See [Results.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/Results.tsx) for an example.
diff --git a/docs/reference/api-react-components-search-box.md b/docs/reference/api-react-components-search-box.md
new file mode 100644
index 000000000..c16f9000e
--- /dev/null
+++ b/docs/reference/api-react-components-search-box.md
@@ -0,0 +1,390 @@
+---
+navigation_title: "React components"
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-search-box.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# SearchBox [api-react-components-search-box]
+
+Input element which accepts search terms and triggers a new search query.
+
+## Example [api-react-components-search-box-example]
+
+```jsx
+import { SearchBox } from "@elastic/react-search-ui";
+
+...
+
+
+```
+
+## Configuring search queries [api-react-components-search-box-configuring-search-queries]
+
+The input from `SearchBox` will be used to trigger a new search query. That query can be further customized in the `SearchProvider` configuration, using the `searchQuery` property. See the [Search Query Configuration](/reference/api-core-configuration.md#api-core-configuration-search-query-queryconfig) guide for more information.
+
+## Example of passing custom props to text input element [api-react-components-search-box-example-of-passing-custom-props-to-text-input-element]
+
+```jsx
+
+```
+
+## Example using autocomplete results [api-react-components-search-box-example-using-autocomplete-results]
+
+"Results" are search results. The default behavior for autocomplete results is to link the user directly to a result when selected, which is why a "titleField" and "urlField" are required for the default view.
+
+```jsx
+
+```
+
+## Example using autocomplete suggestions [api-react-components-search-box-example-using-autocomplete-suggestions]
+
+"Suggestions" are different than "results". Suggestions are suggested queries. Unlike an autocomplete result, a suggestion does not go straight to a result page when selected. It acts as a regular search query and refreshes the result set.
+
+```jsx
+
+```
+
+## Example using autocomplete suggestions and autocomplete results [api-react-components-search-box-example-using-autocomplete-suggestions-and-autocomplete-results]
+
+The default view will show both results and suggestions, divided into sections. Section titles can be added to help distinguish between the two.
+
+```jsx
+
+```
+
+## Example retrieving suggestions from another index [api-react-components-search-box-example-retrieving-suggestions-from-another-index]
+
+::::{important}
+**Supported only by the Elasticsearch-connector.**
+
+::::
+
+A different index can be used for the suggestions. Some examples:
+
+- Popular queries index from analytics
+- Brands index from product data
+- Categories index from product data
+
+Below we are using the `popular_queries` index and performing a prefix match search on the `query.suggest` field. One thing to note, make sure the api-key has access to the index.
+
+### Autocomplete Configuration [api-react-components-search-box-autocomplete-configuration]
+
+```jsx
+autocompleteQuery: {
+ suggestions: {
+ types: {
+ popularQueries: {
+ search_fields: {
+ "query.suggest": {} // fields used to query
+ },
+ result_fields: {
+ query: { // fields used for display
+ raw: {}
+ }
+ },
+ index: "popular_queries",
+ queryType: "results"
+ }
+ },
+ size: 4
+ }
+}
+```
+
+### Component Configuration [api-react-components-search-box-component-configuration]
+
+```jsx
+
+```
+
+You also have the option to customise the `view` of the autocomplete to show more fields.
+
+## Configuring autocomplete queries [api-react-components-search-box-configuring-autocomplete-queries]
+
+Autocomplete queries can be customized in the `SearchProvider` configuration, using the `autocompleteQuery` property. See the [Autocomplete Query Configuration](/reference/api-core-configuration.md) for more information.
+
+```jsx
+
+
+
+```
+
+## Example using multiple types of autocomplete suggestions [api-react-components-search-box-example-using-multiple-types-of-autocomplete-suggestions]
+
+"Suggestions" can be generated via multiple methods. They can be derived from common terms and phrases inside of documents, or be "popular" queries generated from actual search queries made by users. The example below shows how to configure multiple suggestion types using ElasticsearchConnector.
+
+```jsx
+
+
+
+```
+
+## Example using autocomplete in a site header [api-react-components-search-box-example-using-autocomplete-in-a-site-header]
+
+This is an example from a [Gatsby](https://www.gatsbyjs.org/) site, which overrides "submit" to navigate a user to the search page for suggestions, and maintaining the default behavior when selecting a result.
+
+```jsx
+ {
+ navigate("/search?q=" + searchTerm);
+ }}
+ onSelectAutocomplete={(selection, {}, defaultOnSelectAutocomplete) => {
+ if (selection.suggestion) {
+ navigate("/search?q=" + selection.suggestion);
+ } else {
+ defaultOnSelectAutocomplete(selection);
+ }
+ }}
+/>
+```
+
+## Properties [api-react-components-search-box-properties]
+
+| Name | Description |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| className | |
+| shouldClearFilters | Should existing filters be cleared when a new search is performed? |
+| inputProps | Props for underlying _input_ element. I.e., `{ placeholder: "Enter Text"}`. |
+| searchAsYouType | Executes a new search query with every key stroke. You can fine tune the number of queries made by adjusting the `debounceLength` parameter. |
+| debounceLength | When using `searchAsYouType`, it can be useful to "debounce" search requests to avoid creating an excessive number of requests. This controls the length to debounce / wait. |
+| autocompleteResults | Configure and autocomplete search results. Boolean option is primarily available for implementing custom views. |
+| autocompleteSuggestions | Configure and autocomplete query suggestions. Boolean option is primarily available for implementing custom views. Configuration may or may not be keyed by "Suggestion Type", as APIs for suggestions may support may than 1 type of suggestion. If it is not keyed by Suggestion Type, then the configuration will be applied to the first type available. |
+| autocompleteMinimumCharacters | Minimum number of characters before autocompleting. |
+| onSelectAutocomplete | Allows overriding behavior when selected, to avoid creating an entirely new view. In addition to the current `selection`, various helpers are passed as `options` to the second parameter. This third parameter is the default `onSelectAutocomplete`, which allows you to defer to the original behavior. |
+| onSubmit | Allows overriding behavior when submitted. Receives the search term from the search box. |
+| autocompleteView | Used to override only the autocomplete dropdown. See [Autocomplete view customization](#api-react-components-search-box-autocomplete-view-customization) below. |
+| inputView | Used to override only the input box. See [Input view customization](#api-react-components-search-box-input-view-customization) below. |
+| view | Used to override the default view for this Component. See [Full view customization](#api-react-components-search-box-full-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View |
+
+### AutocompleteResultsOptions [api-react-components-search-box-autocompleteresultsoptions]
+
+| Name | Description |
+| ----------------------- | --------------------------------------------------------- |
+| linkTarget | Used to open links in a new tab. |
+| sectionTitle | Title to show in section within dropdown. |
+| shouldTrackClickThrough | Only applies to Results, not Suggestions. |
+| clickThroughTags | Tags to send to analytics API when tracking clickthrough. |
+| titleField | Field within a Result to use as the "title". |
+| urlField | Field within a Result to use for linking. |
+
+### AutocompleteSuggestionsOptions [api-react-components-search-box-autocompletesuggestionsoptions]
+
+| Name | Description |
+| ------------ | ---------------------------------------- |
+| sectionTitle | Title to show in section within dropdown |
+
+## View customization [api-react-components-search-box-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+### Full view customization [api-react-components-search-box-full-view-customization]
+
+You can customize the entire view using the `view` prop. This is useful to use an entirely different autocomplete library (we use [downshift](https://github.com/downshift-js/downshift)). A SearchBox component at its simplest could look like the following:
+
+```jsx
+ (
+
+ )}
+/>
+```
+
+The full list of props available to this view are as follows:
+
+| Name | Description |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| className | Passed through from main component. |
+| inputView | Component to use for text input. When rendering, pass all props documented below in the [Input view customization](#api-react-components-search-box-input-view-customization) section.
Note that this can be challenging to do since some of the required props are generated by Downshift. It's generally advised not to try to use this property directly when creating a custom view. |
+| isFocused | Type: `boolean`. Whether or not the input currently has focus. Will only work if you have correct spread `inputProps` over your input box. |
+| onChange | Type: `(value: string) => void`. When a user changes the input of the search input box, call this with the new value. |
+| onSubmit | Type: `(e: FormEvent) => void`. Handle a "submission" of the search box. Typically used directly on a `form` element surrounding your input box. |
+| value | Type: `string`. The current user input to show in the input box. |
+| inputProps | An object containing props that should be spread over the input box element. You'll need to do this in order to have the `isFocused` prop work. |
+| autocompleteView | Component to use for Autocomplete. When rendering, pass all props documented below in the [Autocomplete view customization](#api-react-components-search-box-autocomplete-view-customization) section.
Note that this can be challenging to do since some of the required props are generated by Downshift. It's generally advised not to try to use this property directly when creating a custom view. |
+| completeSuggestion | Type: `(searchQuery: string) => void`. |
+| notifyAutocompleteSelected | Type: `(selection: any) => void`. |
+| autocompletedSuggestionsCount | Type: `number`. |
+| autocompleteSuggestions | Type: `boolean | AutocompleteSuggestion`. |
+| autocompletedSuggestions | Type: `AutocompletedSuggestions`. |
+| autocompletedResults | Type: `AutocompletedResult[]`. |
+| autocompleteResults | Type: `AutocompleteResult | boolean`. |
+| onSelectAutocomplete | Type: `(selectedItem: any) => void`. Call this with the selected item (whether it is a result or a suggestion) when an autocomplete selection is made in the autocomplete dropdown. |
+| allAutocompletedItemsCount | Type: `number`. The number of items that would be shown in an autocomplete. If 0, no need to show the autocomplete. |
+| useAutocomplete | Type: `boolean`. Whether or not to show an autocomplete dropdown. |
+
+See [SearchBox.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/SearchBox.tsx) for an example.
+
+### Input view customization [api-react-components-search-box-input-view-customization]
+
+For making small customizations, like simply hiding the search button, or rearranging DOM structure, full customization is often overkill.
+
+You can also just customize the input section of the search box using the `inputView` prop.
+
+```jsx
+ (
+ <>
+
+
+ {getAutocomplete()}
+
+
+
+ )}
+/>
+```
+
+Note that `getInputProps` and `getButtonProps` are [prop getters](https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters). They are meant return a props object to spread over their corresponding UI elements. This lets you arrange elements however you'd like in the DOM. It also lets you pass additional properties. You should pass properties through these functions, rather directly on elements, in order to not override base values. For instance, adding a `className` through these functions will assure that the className is only appended, not overriding the base class values.
+
+`getAutocomplete` is used to determine where the autocomplete dropdown will be shown.
+
+The full list of props available to this view are as follows:
+
+| Name | Description |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| getAutocomplete | Type: `() => JSX.Element`. Call this method wherever you would like your autocomplete to appear. Typically, directly below your input box. |
+| getButtonProps | Type: `() => Object`. Spread the return value of this function over your "Search" button, which submit your search. |
+| getInputProps | Type: `() => JSX`. Spread the return value of this function over the `input` element you are using for your search box. |
+
+See [SearchInput.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/SearchInput.tsx) for an example.
+
+### Autocomplete view customization [api-react-components-search-box-autocomplete-view-customization]
+
+In addition to the `inputView` customization, you can also make targed customization to the autocomplete view using the `autocompleteView` prop.
+
+For example:
+
+```jsx
+ (
+
+ {autocompletedResults.map((result, i) => (
+
+ Result {i}: {result.title.snippet}
+
+ ))}
+
+ )}
+/>
+```
+
+The full list of props available to this view are as follows:
+
+| Name | Description |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| allAutocompletedItemsCount | Type: `number`. The number of items that would be shown in an autocomplete. If 0, no need to show the autocomplete. |
+| autocompleteResults | Type: `boolean | AutocompleteResult`. Configuration object passed through from main component. |
+| autocompletedResults | Type: `AutocompletedResult[]`. The search results generated by an autocomplete query. |
+| autocompletedSuggestions | Type: `AutocompletedSuggestions`. The suggestions generated by an autocomplete suggestions query. |
+| autocompletedSuggestionsCount | Type: `number`. The total number of suggestions generated by an autocomplete suggestions query. |
+| autocompleteSuggestions | Type: `boolean | AutocompleteSuggestion`. Configuration object passed through from main component. |
+| onSelectAutocomplete | Type: `(selectedItem: any) => void`. Call this with the selected item (whether it is a result or a suggestion) when an autocomplete selection is made in the autocomplete dropdown. |
+| getItemProps | Type: `{ key: string, index: number, item: AutocompletedSuggestion }) => any`. A function that will generate props to spread over an individual item in the autocomplete list. |
+| getMenuProps | Type: `({ className: string }) => any`. A function that will generate props to spread over the main autocomplete dropdown element. |
+
+See [Autocomplete.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/Autocomplete.tsx) for an example.
diff --git a/docs/reference/api-react-components-sorting.md b/docs/reference/api-react-components-sorting.md
new file mode 100644
index 000000000..2cb710a38
--- /dev/null
+++ b/docs/reference/api-react-components-sorting.md
@@ -0,0 +1,60 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-components-sorting.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Sorting [api-react-components-sorting]
+
+Shows a dropdown for selecting the current Sort.
+
+## Example [api-react-components-sorting-example]
+
+```jsx
+import { Sorting } from "@elastic/react-search-ui";
+
+...
+
+
+```
+
+## Properties [api-react-components-sorting-properties]
+
+| Name | Description |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| className | |
+| label | A static label to show in the Sorting Component. |
+| sortOptions | |
+| view | Used to override the default view for this Component. See [View customization](#api-react-components-sorting-view-customization) below. |
+| \* | Any other property passed will be passed through and available to use in a Custom View |
+
+## View customization [api-react-components-sorting-view-customization]
+
+A complete guide to view customization can be found in the [Customization: Component views and HTML](/reference/basic-usage.md#guides-customizing-styles-and-html-customizing-html) section.
+
+The following properties are available in the view:
+
+| Name | Description |
+| --------- | --------------------------------------------------------------------------------------- |
+| className | Passed through from main component. |
+| label | The label to display for this component. For example: "Sort by". |
+| onChange | function(value: string) - Pass the value to this callback from the selected sort option |
+| options | `{ value: string; label: string;}[]` - Options to display |
+| value | string - The currently selected value |
+
+See [Sorting.tsx](https://github.com/elastic/search-ui/blob/main/packages/react-search-ui-views/src/Sorting.tsx) for an example.
diff --git a/docs/reference/api-react-search-provider.md b/docs/reference/api-react-search-provider.md
new file mode 100644
index 000000000..603ea5f18
--- /dev/null
+++ b/docs/reference/api-react-search-provider.md
@@ -0,0 +1,95 @@
+---
+navigation_title: "React API"
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-search-provider.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# SearchProvider [api-react-search-provider]
+
+The `SearchProvider` is a React wrapper around the Headless Core, and makes state and actions available to Search UI and in a React [Context](https://reactjs.org/docs/context.html), and also via a [Render Prop](https://reactjs.org/docs/render-props.html).
+
+It looks like this:
+
+```jsx
+import { SearchProvider, SearchBox } from "@elastic/react-search-ui";
+import ElasticSearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";
+
+const connector = new ElasticSearchAPIConnector({
+ host: "https://search-ui-sandbox.es.us-central1.gcp.cloud.es.io:9243",
+ index: "national-parks",
+ apiKey: "WnRHcE9wb0Jzb241b2hqX1lTcnM6X0syVXBuQXVUTjZwSlRTbFNyTVlDUQ=="
+});
+
+const configurationOptions = {
+ apiConnector: connector,
+ searchQuery: { ... },
+ autocompleteQuery: { ... },
+ hasA11yNotifications: true,
+ a11yNotificationMessages: {
+ searchResults: ({ start, end, totalResults, searchTerm }) =>
+ `Searching for "${searchTerm}". Showing ${start} to ${end} results out of ${totalResults}.`
+ },
+ alwaysSearchOnInitialLoad: true
+};
+
+const App = () => (
+
+
+
+
+
+);
+```
+
+| option | type | description |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiConnector` | APIConnector | Instance of a Connector. See Connectors API section. |
+| `onSearch` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. |
+| `onAutocomplete` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. |
+| `onResultClick` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. |
+| `onAutocompleteResultClick` | function | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. |
+| `autocompleteQuery` | [Autocomplete Query Config](/reference/api-core-configuration.md#api-core-configuration-autocomplete-query) | Configuration options for the autocomplete query. |
+| `debug` | Boolean | Trace log actions and state changes. Default is false. |
+| `initialState` | Object | Set inital state of Search UI. See [Initial State](#api-react-search-provider-initial-state) for more information. |
+| `searchQuery` | [Search Query Config](/reference/api-core-configuration.md#api-core-configuration-search-query-queryconfig) | Configuration options for the main search query. |
+| `trackUrlState` | Boolean | By default, [Request State](/reference/api-core-state.md#api-core-state-request-state) will be synced with the browser url. To turn this off, pass `false`. |
+| `urlPushDebounceLength` | Integer | The amount of time in milliseconds to debounce/delay updating the browser url after the UI update. This, for example, prevents excessive history entries while a user is still typing in a live search box. Default is 500. |
+| `hasA11yNotifications` | Boolean | Search UI will create a visually hidden live region to announce search results & other actions to screen reader users. This accessibility feature will be turned on by default in our 2.0 release. Default is false. |
+| `a11yNotificationMessages` | Object | You can override our default screen reader packages/search-ui/src/A11yNotifications.js#L49[messages] (e.g. for localization), or create your own custom notification, by passing in your own key and message function(s). |
+| `alwaysSearchOnInitialLoad` | Boolean | If true, Search UI will always do an initial search, even when no inital Request State is set. |
+
+## Context [api-react-search-provider-context]
+
+The "Context" is a flattened object containing, as keys, all [State](/reference/api-core-state.md) and [Actions](/reference/api-core-actions.md).
+
+We refer to it as "Context" because it is implemented with a [React Context](https://reactjs.org/docs/context.html).
+
+ex.
+
+```js
+{
+ resultsPerPage: 10, // Request State
+ setResultsPerPage: () => {}, // Action
+ current: 1, // Request State
+ setCurrent: () => {}, // Action
+ error: '', // Response State
+ isLoading: false, // Response State
+ totalResults: 1000, // Response State
+ ...
+}
+```
+
+## Initial State [api-react-search-provider-initial-state]
+
+This is useful for defaulting a search term, sort, etc.
+
+Example
+
+```js
+ initialState: { searchTerm: "test", resultsPerPage: 40 }
+```
+
+See [Request State](/reference/api-core-state.md) for more properties that can be set in initial state.
diff --git a/docs/reference/api-react-use-search.md b/docs/reference/api-react-use-search.md
new file mode 100644
index 000000000..4b2750d37
--- /dev/null
+++ b/docs/reference/api-react-use-search.md
@@ -0,0 +1,40 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-use-search.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# useSearch hook [api-react-use-search]
+
+In addition, to using `withSearch` you can now use `useSearch` hook in your custom react functional component.
+
+## Usage
+
+In order to use this hook, you should wrap your functional component in `SearchProvider`. We will see an example on how to use useSearch hook to render "loading" indicator when the application is fetching data.
+
+```
+const Component = () => {
+ const { isLoading } = useSearch();
+ return (
+
+ );
+};
+export const App = () => {
+ return (
+
+
+
+ );
+};
+
+```
diff --git a/docs/api-react-hocs.mdx b/docs/reference/api-react-with-search.md
similarity index 58%
rename from docs/api-react-hocs.mdx
rename to docs/reference/api-react-with-search.md
index 077a60ce5..c1458f70f 100644
--- a/docs/api-react-hocs.mdx
+++ b/docs/reference/api-react-with-search.md
@@ -1,26 +1,22 @@
---
-id: api-react-hocs
-slug: /search-ui/api/react/hocs
-title: Connectors
-date: 2022-03-31
-tags: ["component hocs"]
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-with-search.html
+applies_to:
+ stack:
+ serverless:
---
-If you wish to use Search UI and build your own custom component, you will need to use our HOCs to use Search UI's core state and actions.
+# WithSearch & withSearch [api-react-with-search]
-There are two HOCs for accessing Search UI's state & actions, `withSearch` and
-`WithSearch`. They use the [HOC](https://reactjs.org/docs/higher-order-components.html) and
-[Render Props](https://reactjs.org/docs/render-props.html) patterns, respectively. The two methods
-are similar, and choosing between the two is mostly personal preference.
+If you wish to use Search UI and build your own custom component, you will need to use our HOCs to use Search UI’s core state and actions.
-Both methods expose a `mapContextToProps` function which allows you to pick which state and actions
-from context you need to work with.
+There are two HOCs for accessing Search UI’s state & actions, `withSearch` and `WithSearch`. They use the [HOC](https://reactjs.org/docs/higher-order-components.html) and [Render Props](https://reactjs.org/docs/render-props.html) patterns, respectively. The two methods are similar, and choosing between the two is mostly personal preference.
-### mapContextToProps
+Both methods expose a `mapContextToProps` function which allows you to pick which state and actions from context you need to work with.
-`mapContextToProps` allows you to pick which state and actions
-from Context you need to work with. `withSearch` and `WithSearch` both use [React.PureComponent](https://reactjs.org/docs/react-api.html#reactpurecomponent),
-and will only re-render when the picked state has changed.
+## mapContextToProps [api-react-with-search-mapcontexttoprops]
+
+`mapContextToProps` allows you to pick which state and actions from Context you need to work with. `withSearch` and `WithSearch` both use [React.PureComponent](https://reactjs.org/docs/react-api.html#reactpurecomponent), and will only re-render when the picked state has changed.
| name | type | description |
| ------- | ------ | ------------------- |
@@ -53,16 +49,15 @@ withSearch(({ searchTerm }, { someProp }) => ({
}))(Component);
```
-### withSearch
+## withSearch [api-react-with-search-withsearch]
-This is the [HOC](https://reactjs.org/docs/higher-order-components.html) approach to working with the
-core.
+This is the [HOC](https://reactjs.org/docs/higher-order-components.html) approach to working with the core.
This is typically used for creating your own Components.
-See [Build Your Own Component](#build-your-own-component).
+See [Build Your Own Component](/reference/guides-creating-own-components.md).
-### WithSearch
+## WithSearch [api-react-with-search-withsearch-1]
This is the [Render Props](https://reactjs.org/docs/render-props.html) approach to working with the core.
diff --git a/docs/guides-philosphy.mdx b/docs/reference/api-reference.md
similarity index 76%
rename from docs/guides-philosphy.mdx
rename to docs/reference/api-reference.md
index d7a219ff5..ccba72c13 100644
--- a/docs/guides-philosphy.mdx
+++ b/docs/reference/api-reference.md
@@ -1,14 +1,15 @@
---
-id: guides-philosophy
-slug: /search-ui/guides/philosophy
-title: Philosophy
-date: 2022-02-27
-tags: ["philosophy"]
+navigation_title: "API reference"
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-architecture.html
+applies_to:
+ stack:
+ serverless:
---
-## Headless Core Concepts
+# Architecture [api-architecture]
-```
+```txt
|
@elastic/react-search-ui | @elastic/search-ui
|
@@ -32,8 +33,6 @@ The core is a separate, vanilla JS library which can be used for any JavaScript
The Headless Core implements the functionality behind a search experience, but without its own view. It provides the underlying "state" and "actions" associated with that view. For instance, the core provides a `setSearchTerm` action, which can be used to save a `searchTerm` property in the state. Calling `setSearchTerm` using the value of an `` will save the `searchTerm` to be used to build a query.
-All of the Components in this library use the Headless Core under the hood. For instance, Search UI provides a `SearchBox` Component for collecting input from a user. But you are not restricted to using just that Component. Since Search UI lets you work directly with "state" and "actions", you could use any type of input you want! As long as your input or Component calls the Headless Core's `setSearchTerm` action, it will "just work". This gives you maximum flexibility over your experience if you need more than the Components in Search UI have to offer.
+All of the Components in this library use the Headless Core under the hood. For instance, Search UI provides a `SearchBox` Component for collecting input from a user. But you are not restricted to using just that Component. Since Search UI lets you work directly with "state" and "actions", you could use any type of input you want! As long as your input or Component calls the Headless Core’s `setSearchTerm` action, it will "just work". This gives you maximum flexibility over your experience if you need more than the Components in Search UI have to offer.
-The `SearchProvider` is a React wrapper around the Headless Core, and makes state and actions available to Search UI
-and in a React [Context](https://reactjs.org/docs/context.html), and also via a
-[Render Prop](https://reactjs.org/docs/render-props.html).
+The `SearchProvider` is a React wrapper around the Headless Core, and makes state and actions available to Search UI and in a React [Context](https://reactjs.org/docs/context.html), and also via a [Render Prop](https://reactjs.org/docs/render-props.html).
diff --git a/docs/reference/basic-usage.md b/docs/reference/basic-usage.md
new file mode 100644
index 000000000..55fec4d5a
--- /dev/null
+++ b/docs/reference/basic-usage.md
@@ -0,0 +1,97 @@
+---
+navigation_title: "Basic usage"
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/guides-customizing-styles-and-html.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Customizing Styles and HTML [guides-customizing-styles-and-html]
+
+In this guide we’ll customize some styles of the Search UI, modify the default HTML of one of the Search UI components, and also create a completely new Result component.
+
+:::{tip}
+See this code in action in our [live CodeSandbox demo](https://codesandbox.io/embed/github/elastic/search-ui/tree/main/examples/sandbox?autoresize=1&fontsize=12&initialpath=%2Fcustomizing-styles-and-html&module=%2Fsrc%2Fpages%2Fcustomizing-styles-and-html%2Findex.jsx).
+:::
+
+## Customizing styles [guides-customizing-styles-and-html-customizing-styles]
+
+We provide a default stylesheet to get your project started quickly.
+
+```jsx
+import "@elastic/react-search-ui-views/lib/styles/styles.css";
+```
+
+You could choose to add your own stylesheet to override or augment these styles:
+
+```jsx
+import "@elastic/react-search-ui-views/lib/styles/styles.css";
+import "your-custom-styles.css";
+```
+
+You could also choose to replace these styles completely with your own stylesheet:
+
+```jsx
+import "your-custom-styles.css";
+```
+
+When target styles to override, we generally advise that you rely only on styles that are prefixed with `.sui`. We try to keep these compatible for version upgrades so that we don’t break your custom styles. However, we do recommend that you test your styles thoroughly when upgrading versions, even within minors.
+
+Here is an example of a simple stylesheet that overrides much of the blue in the base styles with red to create a simple red theme:
+
+```css
+.sui-search-box__submit {
+ background: none;
+ background-color: red;
+}
+
+.sui-layout-sidebar-toggle {
+ color: red;
+ border: 1px solid red;
+}
+
+.sui-result__title,
+.sui-result__title-link {
+ color: red;
+}
+
+.sui-facet-view-more {
+ color: red;
+}
+```
+
+## Customizing html [guides-customizing-styles-and-html-customizing-html]
+
+All components in this library can be customized by providing a `view` prop.
+
+The view prop can be used to customize a component’s look and feel while still maintaining the component’s logic.
+
+This follows the [React Render Props](https://reactjs.org/docs/render-props.html) pattern. The `view` prop is a function. The various logic and values your view needs are passed through as parameters to the `view` function you provide.
+
+Every component will have a different function signature for its view.
+
+Here is an example of a custom view being provided for the `PagingInfo` component:
+
+```jsx
+ (
+
+ );
+}
+```
+
+Should you find the search bar markup too limiting to your needs, you can override the display using the optional `inputView` `autocompleteView` and `resultsView` props.
+
+```jsx
+ (
+
+ {autocompletedResults.map((result, i) => (
+
+ Result {i}: {result.title.snippet}
+
+ ))}
+
+ )}
+/>
+```
+
+For more information of whats possible to customise, see [searchbox autocomplete documentation](/reference/api-react-components-search-box.md).
+
+## Term Suggestions [solutions-ecommerce-autocomplete-term-suggestions]
+
+Term Suggestions help the customer quickly type in the search term. The suggestions are based on keywords that are already present in the index. To do this, you need:
+
+- An engine or index populated with products
+
+To configure the SearchBox to provide suggestions based on keywords, you need to pass a `config` object to the `SearchProvider` component and configure the `Searchbox autocompleteSuggestions` to be true.
+
+% TO DO: Use `:class: screenshot`
+
+
+Example Code
+
+:::::::{tab-set}
+
+::::::{tab-item} Configuration
+
+```jsx
+const config = {
+ autocompleteQuery: {
+ resultsPerPage: 5,
+ result_fields: {
+ name: { snippet: { size: 100, fallback: true } },
+ url: { raw: {} }
+ },
+ search_fields: {
+ name_product_autocomplete: {}
+ }
+ }
+};
+```
+
+::::::
+
+::::::{tab-item} Searchbox Component
+
+```jsx
+
+```
+
+::::::
+
+:::::::
+
+## Product Suggestions [solutions-ecommerce-autocomplete-product-suggestions]
+
+With this feature, products will be presented as suggestions to the customer. When the customer clicks on the product suggestion, they will be navigated straight to the product’s detail page.
+
+% TO DO: Use `:class: screenshot`
+
+
+First, we specify the `autocompleteQuery.results` configuration:
+
+:::::::{tab-set}
+
+::::::{tab-item} Configuration
+
+```jsx
+const config = {
+ alwaysSearchOnInitialLoad: false,
+ autocompleteQuery: {
+ results: {
+ resultsPerPage: 5,
+ result_fields: {
+ // specify the fields you want from the index to display the results
+ image: { raw: {} },
+ name: { snippet: { size: 100, fallback: true } },
+ url: { raw: {} }
+ },
+ search_fields: {
+ // specify the fields you want to search on
+ name: {}
+ }
+ }
+ },
+ apiConnector: connector
+};
+```
+
+::::::
+
+::::::{tab-item} Searchbox Component
+
+```jsx
+
+```
+
+::::::
+
+::::::{tab-item} Autocomplete View Component
+
+````jsx
+ function AutocompleteView({
+ autocompleteResults,
+ autocompletedResults,
+ autocompleteSuggestions,
+ autocompletedSuggestions,
+ className,
+ getItemProps,
+ getMenuProps
+ }) {
+ let index = 0;
+ return (
+
+ {getSuggestionTitle(
+ suggestionType,
+ autocompleteSuggestions
+ )}
+::::::
+
+:::::::
+
+## Suggestions from another source index [solutions-ecommerce-autocomplete-suggestions-from-another-source-index]
+
+::::{important}
+**Requires Elasticsearch Connector.**
+
+::::
+
+
+Sometimes you want to display suggestions from a different index than the one you use for search. For example, you might want to show suggestions from a `popular_queries` or a `designers` index. Search UI supports this within the `autocompleteSuggestions` configuration.
+
+In this example, we will populate an index with popular queries. The mapping and example documents for the index will be as follows:
+
+:::::::{tab-set}
+
+::::::{tab-item} Mapping
+```json
+{
+ "popular_queries" : {
+ "mappings" : {
+ "properties" : {
+ "name" : {
+ "type" : "text",
+ "fields" : {
+ "suggest" : {
+ "type" : "search_as_you_type",
+ "doc_values" : false,
+ "max_shingle_size" : 3
+ }
+ }
+ }
+ }
+ }
+ }
+}
+````
+
+::::::
+
+::::::{tab-item} Example Document
+
+```json
+{
+ "name": "Iphone 4s"
+}
+```
+
+::::::
+
+:::::::
+Next, setup Search UI `Searchbox` and `configuration` to display suggestions from the `popular_queries` index.
+
+:::::::{tab-set}
+
+::::::{tab-item} Search Configuration
+
+```jsx
+const config = {
+ alwaysSearchOnInitialLoad: false,
+ autocompleteQuery: {
+ suggestions: {
+ types: {
+ popularQueries: {
+ search_fields: {
+ "name.suggest": {} // fields used to query
+ },
+ result_fields: {
+ name: {
+ raw: {}
+ }
+ },
+ index: "popular_queries",
+ queryType: "results"
+ }
+ },
+ size: 4
+ }
+ },
+ apiConnector: connector
+};
+```
+
+::::::
+
+::::::{tab-item} Searchbox Component Configuration
+
+```jsx
+
+```
+
+::::::
+
+:::::::
+Now, when you type `was` in the SearchBox, the autocomplete view will display the popular queries:
+
+% TO DO: Use `:class: screenshot`
+
+
+If you want to display more fields from the index, you can use the `result_fields` configuration and implement a custom `autocompleteView` to display these fields.
+
+## Suggestions from multiple sources [solutions-ecommerce-autocomplete-suggestions-from-multiple-sources]
+
+Combining the suggestion configurations above allows you to display suggestions from multiple sources simultaneously.
+
+% TO DO: Use `:class: screenshot`
+
+
+To do this, extend the `autocompleteQuery` configuration to specify multiple sources. For example, in the screenshot above, we customized the `autocompleteView` CSS to display the popular queries and the results from the `autocompleteSuggestions` configuration side by side and hide the section titles.
+
+:::::::{tab-set}
+
+::::::{tab-item} Search Configuration
+
+```jsx
+const config = {
+ alwaysSearchOnInitialLoad: false,
+ autocompleteQuery: {
+ suggestions: {
+ types: {
+ popularQueries: {
+ search_fields: {
+ "name.suggest": {} // fields used to query
+ },
+ result_fields: {
+ name: {
+ raw: {}
+ }
+ },
+ index: "popular_queries",
+ queryType: "results"
+ }
+ },
+ size: 4
+ }
+ },
+ apiConnector: connector
+};
+```
+
+::::::
+
+::::::{tab-item} Searchbox Component Configuration
+
+```jsx
+
+```
+
+::::::
+
+:::::::
+
+## Related Articles [solutions-ecommerce-autocomplete-related-articles]
+
+- [Adding search bar to header](/reference/guides-adding-search-bar-to-header.md)
+- [React components](/reference/api-react-components-search-box.md)
+- [Changing component behavior](/reference/guides-changing-component-behavior.md)
diff --git a/docs/reference/solutions-ecommerce-carousel.md b/docs/reference/solutions-ecommerce-carousel.md
new file mode 100644
index 000000000..e41cc7a22
--- /dev/null
+++ b/docs/reference/solutions-ecommerce-carousel.md
@@ -0,0 +1,78 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/solutions-ecommerce-carousel.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Product Carousels [solutions-ecommerce-carousel]
+
+:::{warning}
+This example uses the App Search connector, which is now deprecated and will no longer be supported. Please use [Elasticsearch Connector](/reference/api-connectors-elasticsearch.md).
+:::
+
+Carousels can be used to show groups of products into a row and are typically used to show products within a specific category or tag, like "most popular", "best rated" and "on sale".
+
+In this example, we show a carousel of products within the "TVs" category using the `Results` component and overriding the `view`.
+
+You can adjust the number of results returned via the `resultsPerPage` configuration.
+
+% TO DO: Use `:class: screenshot`
+
+
+:::::::{tab-set}
+
+::::::{tab-item} Component
+
+````jsx
+ import { Results, SearchProvider } from "@elastic/react-search-ui";
+ import { config } from "./config";
+
+ const CustomResultsView = ({ children }) => {
+ return (
+
+
{children}
+::::::
+
+::::::{tab-item} Search UI Config
+```js
+import AppSearchAPIConnector from "@elastic/search-ui-app-search-connector";
+
+const connector = new AppSearchAPIConnector({
+searchKey: "",
+engineName: "",
+endpointBase: "",
+});
+
+export const config = () => ({
+ alwaysSearchOnInitialLoad: true,
+ trackUrlState: false,
+ initialState: {
+ resultsPerPage: 8
+ },
+ searchQuery: {
+ filters: [{ field: "parent_category", values: ["TVs"] }],
+ result_fields: {
+ name: {
+ raw: {}
+ },
+ image: { raw: {} },
+ url: { raw: {} }
+ }
+ },
+ apiConnector: connector
+});
+````
+
+::::::
+
+:::::::
+
+:::{tip}
+[Try the demo in CodeSandbox](https://codesandbox.io/embed/github/elastic/search-ui/tree/main/examples/sandbox?autoresize=1&fontsize=12&initialpath=%2Fecommerce&module=%2Fsrc%2Fpages%2Fecommerce%2Findex.jsx).
+:::
+
+- [Creating Components](/reference/guides-creating-own-components.md): Build your own components for Search UI.
+- [Results](/reference/api-react-components-results.md): Search UI React Results Component.
+- [Core API](/reference/api-core-configuration.md): Search UI Configuration API.
diff --git a/docs/reference/solutions-ecommerce-category-page.md b/docs/reference/solutions-ecommerce-category-page.md
new file mode 100644
index 000000000..cb24b38a5
--- /dev/null
+++ b/docs/reference/solutions-ecommerce-category-page.md
@@ -0,0 +1,316 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/solutions-ecommerce-category-page.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Category Page [solutions-ecommerce-category-page]
+
+This is a category page:
+
+% TO DO: Use `:class: screenshot`
+
+
+At first glance, the category page looks very similar to a search page — they display a list of products and have facets to help users refine the results. But while the search page is made for "searching" the entire catalog by typing a query, the category page is made for "exploring" a small subset of products with the help of filters.
+
+On the screenshot above, we are only exploring the "Women’s Athletic Shoes" section of the catalog.
+
+In this article, we will talk about how to implement a product category page with Search UI.
+
+:::{tip}
+See the category page demo in action in [CodeSandbox](https://codesandbox.io/embed/github/elastic/search-ui/tree/main/examples/sandbox?autoresize=1&fontsize=12&initialpath=%2Fecommerce%2Fcategory%2FTVs&module=%2Fsrc%2Fpages%2Fecommerce%2Findex.jsx).
+:::
+
+## Applying Filters to the Category Page [solutions-ecommerce-category-page-applying-filters-to-the-category-page]
+
+It’s important to consider the SEO of a category page. Some of your customers will come from search engines, and having a good-looking URL will help you rank higher.
+
+Let’s say we want to have a category page for TVs. You can do it by taking a search page and applying a filter to only show TVs.
+
+Now, if we do so on a search page, we’ll have a URL like this:
+
+```txt
+mystore.com/search?filters%5B0%5D%5Bfield%5D=categories&filters%5B0%5D%5Bvalues%5D%5B0%5D=TVs
+```
+
+Not very readable!
+
+What we want instead is to have a URL like this:
+
+```txt
+mystore.com/category/tvs/
+```
+
+To achieve that, we’ll need to:
+
+1. Create the category page in our application;
+2. Apply a filter via Search UI config.
+
+The first part is highly dependent on your application’s framework. Refer to its documentation for creating a new page.
+
+For the second part, copy the Search UI config from the search page and add the `searchQuery.filters` value. Then pass the new config to your `SearchProvider`:
+
+```jsx
+// import your Search UI config
+import { config } from "./config";
+import { SearchProvider, WithSearch } from "@elastic/react-search-ui";
+
+const categoryTvsConfig = {
+ ...config,
+ searchQuery: {
+ ...config.searchQuery,
+ // adding a filter to only show TVs
+ filters: [{ field: "parent_category", values: ["TVs"] }]
+ }
+};
+
+export default function CategoryPageTvs() {
+ return (
+ // Pass the new config to SearchProvider
+
+ ({})}>
+ {() => {
+ // The components you want to render go here
+ }}
+
+
+ );
+}
+```
+
+That’s it! The new category page has a good URL and only shows results that match the filter.
+
+## Facets [solutions-ecommerce-category-page-facets]
+
+% TO DO: Use `:class: screenshot`
+
+
+Facets are the essential part of the category page. Since category pages typically don’t have a search box, facets become the primary tool for finding the products.
+
+_Facets let users **explore** what’s available in your store rather than **search** for a specific product._
+
+It’s best to provide facets that are unique to the presented category.
+
+In our example of the TVs category page, in addition to common facets, like:
+
+- Price
+- Brand
+- Rating
+
+we also have TV-specific facets:
+
+- Smart TV _(boolean)_
+- TV resolution _(string: "Full HD", "4k", etc.)_
+- TV diagonal _(number)_
+
+These TV-specific facets are not useful on the search page since they are not relevant to most of the results.
+
+
+There are several ways to implement this in Search UI. They offer different levels of control and flexibility.
+
+1. All category pages share a single config. It is the simplest option to implement but is also the least flexible and performant.
+2. All category pages share a single config, but the facets are shown conditionally. It is a middle ground in simplicity and flexibility and is as performant as the next option.
+3. Each category page uses a separate config. It is the most flexible and most performant option, but it requires more work to implement.
+
+### Single config [solutions-ecommerce-category-page-single-config]
+
+You can use a single Search UI config on the search page and all category pages. However, it comes with a performance drawback: the facets data will be requested on every page even if it’s not used. The decision is up to you: a single config will work as well as separate configs if most of your documents share the same properties.
+
+To implement this, you’ll need to:
+
+1. Add new result fields to `searchQuery.resultFields`
+2. Add new facets to `searchQuery.facets`
+3. (optional) Add new disjunctiveFacets `searchQuery.disjunctiveFacets`
+
+Then, add the `Facet` components to UI.
+
+The resulting code will look something like this:
+
+```jsx
+// import your Search UI config
+import { SearchProvider, WithSearch } from "@elastic/react-search-ui";
+
+const config = {
+ searchQuery: {
+ // 1. Adding new resilt fields, these will be used for the facets
+ result_fields: {
+ tv_size: { raw: {} },
+ tv_smart_tv: { raw: {} },
+ tv_resolution: { raw: {} }
+ // some other fields
+ },
+ // 2. Adding the new facets
+ facets: {
+ tv_size: {
+ type: "value",
+ sort: { value: "asc" }
+ },
+ tv_smart_tv: {
+ type: "value"
+ },
+ tv_resolution: {
+ type: "value",
+ sort: { value: "asc" }
+ }
+ // some other facets
+ },
+ // 3. Making some of newly added facets disjunctive
+ disjunctiveFacets: ["tv_size", "tv_resolution"]
+ }
+};
+
+export default function CategoryPage() {
+ return (
+ // Pass the config to SearchProvider
+
+ ({})}>
+ {() => {
+ return (
+ // The components you want to render go here
+ // For the sake of brevity, we're only showing the new facets
+ <>
+
+
+
+
+ );
+ }}
+
+
+ );
+}
+```
+
+### Conditional facets [solutions-ecommerce-category-page-conditional-facets]
+
+Search UI allows you to show facets conditionally based on the applied filters. Follow the main guide for more info and code examples: [Conditional facets](/reference/guides-conditional-facets.md).
+
+### Separate configs [solutions-ecommerce-category-page-separate-configs]
+
+This option closely follows the single config option but requires you to make a copy of the main Search UI config (that you use on the search page) first.
+
+1. Import and make a copy of the main Search UI config
+2. Add new result fields to `searchQuery.resultFields`
+3. Add new facets to `searchQuery.facets`
+4. (optional) Add new disjunctiveFacets `searchQuery.disjunctiveFacets`
+
+Then, add the `Facet` components to UI.
+
+Here’s how to do it all at once:
+
+```jsx
+// import your Search UI config
+import { config } from "./config";
+import { SearchProvider, WithSearch } from "@elastic/react-search-ui";
+
+const categoryTvsConfig = {
+ ...config,
+ searchQuery: {
+ ...config.searchQuery,
+ filters: [{ field: "parent_category", values: ["TVs"] }],
+ // 1. Adding new resilt fields, these will be used for the facets
+ result_fields: {
+ ...config.searchQuery.result_fields,
+ tv_size: { raw: {} },
+ tv_smart_tv: { raw: {} },
+ tv_resolution: { raw: {} }
+ },
+ // 2. Adding the new facets
+ facets: {
+ ...config.searchQuery.facets,
+ tv_size: {
+ type: "value",
+ sort: { value: "asc" }
+ },
+ tv_smart_tv: {
+ type: "value"
+ },
+ tv_resolution: {
+ type: "value",
+ sort: { value: "asc" }
+ }
+ },
+ // 3. Making some of newly added facets disjunctive
+ disjunctiveFacets: [
+ ...config.searchQuery.disjunctiveFacets,
+ "tv_size",
+ "tv_resolution"
+ ]
+ }
+};
+
+export default function CategoryPageTvs() {
+ return (
+ // Pass the new config to SearchProvider
+
+ ({})}>
+ {() => {
+ return (
+ // The components you want to render go here
+ // For the sake of brevity, we're only showing the new facets
+ <>
+
+
+
+
+ );
+ }}
+
+
+ );
+}
+```
+
+### Example [solutions-ecommerce-category-page-example]
+
+Search UI offers several kinds of facets out-of-the-box:
+
+- MultiCheckboxFacet
+- BooleanFacet
+- SingleLinksFacet
+
+Here’s an example of how to use them:
+
+```jsx
+import { BooleanFacet, SingleLinksFacet } from "@elastic/react-search-ui-views";
+
+
+
+
+```
+
+And the resulting UI:
+
+% TO DO: Use `:class: screenshot`
+
+
+You might need a facet that Search UI doesn’t offer, for example, a dedicated color-picker. With Search UI, you can build a custom facet that will work like a native one. Refer to the [Creating custom components guide](/reference/guides-creating-own-components.md) to learn how.
+
+## Variants [solutions-ecommerce-category-page-variants]
+
+See the main guide for more info about variants: [Variants guide](/reference/solutions-ecommerce-search-page.md#solutions-ecommerce-search-page-variants).
+
+## Sorting [solutions-ecommerce-category-page-sorting]
+
+See the main guide for more info about sorting: [Sorting guide](/reference/solutions-ecommerce-search-page.md#solutions-ecommerce-search-page-sorting).
+
+## Related Articles [solutions-ecommerce-category-page-related-articles]
+
+- [Core API](/reference/api-core-configuration.md): Search UI Configuration API.
+- [Facet](/reference/api-react-components-facet.md)
+- [Creating Components](/reference/guides-creating-own-components.md): Build your own components for Search UI.
diff --git a/docs/reference/solutions-ecommerce-product-detail-page.md b/docs/reference/solutions-ecommerce-product-detail-page.md
new file mode 100644
index 000000000..38ae48f2d
--- /dev/null
+++ b/docs/reference/solutions-ecommerce-product-detail-page.md
@@ -0,0 +1,35 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/solutions-ecommerce-product-detail-page.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Product Detail Page [solutions-ecommerce-product-detail-page]
+
+% TO DO: Use `:class: screenshot`
+
+
+You can put many things on a product detail page: image, description, specs. They are all describing the product itself.
+
+But a critical piece that often gets overlooked is cross-sell recommendations.
+
+% TO DO: Use `:class: screenshot`
+
+
+These are the lists of products located under the product description. They often come under such headings:
+
+- People who viewed this item also viewed
+- Often bought together
+- You might also like
+- etc.
+
+Cross-sell recommendations help users find the right product if the current one does not satisfy their criteria or find the related products faster (for example, frying pan + lid).
+
+Technically, cross-sell recommendations are usually implemented as product carousels. To build one, check out our [Product carousel guide](/reference/solutions-ecommerce-carousel.md), which has an implementation example.
+
+## Related Articles [solutions-ecommerce-product-detail-page-related-articles]
+
+- [Product Carousels](/reference/solutions-ecommerce-carousel.md): Build a product carousel with Search UI.
+- [Creating Components](/reference/guides-creating-own-components.md): Build your own components for Search UI.
diff --git a/docs/reference/solutions-ecommerce-search-page.md b/docs/reference/solutions-ecommerce-search-page.md
new file mode 100644
index 000000000..4e6450a25
--- /dev/null
+++ b/docs/reference/solutions-ecommerce-search-page.md
@@ -0,0 +1,193 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/solutions-ecommerce-search-page.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Search Page [solutions-ecommerce-search-page]
+
+:::{warning}
+This example uses the App Search connector, which is now deprecated and will no longer be supported. Please use [Elasticsearch Connector](/reference/api-connectors-elasticsearch.md).
+:::
+
+The most important part of the search page is the relevance of the displayed results.
+
+There are many ways to improve the relevance. In this article we’ll cover:
+
+- tools available in the admin interface,
+- combining similar results with variants,
+- sorting — improved relevance achieved by a user.
+
+## Improving relevance [solutions-ecommerce-search-page-improving-relevance]
+
+App Search offers many tools to improve the relevance of your search results.
+
+### Start with a language optimization [solutions-ecommerce-search-page-start-with-a-language-optimization]
+
+Choosing the correct language during the engine creation is the easiest way to improve the relevance.
+
+Language optimization will fine-tune features like **stemming**, **bigram matching\***, **\*phrase matching**, and **typo tolerance** for your chosen language.
+
+Follow this guide for the exact steps: [Language optimization guide](https://www.elastic.co/guide/en/app-search/current/language-optimization-guide.html).
+
+### Set up relevance tuning [solutions-ecommerce-search-page-set-up-relevance-tuning]
+
+App Search’s relevance tuning feature allows you to fine-tune the order of the results for any given query.
+
+Follow the [Relevance tuning guide](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html) for the full feature description.
+
+### Add synonyms [solutions-ecommerce-search-page-add-synonyms]
+
+This step is optional but can also improve the relevance.
+
+Sometimes users will use a query that doesn’t _exactly_ match your results. You’re selling **couches**, but a user searches for **sofa**? Tough luck!
+
+To solve this problem, App Search offers a Synonyms feature. It lets you create groups of synonyms that will be used for matching.
+
+Our [Synonyms guide](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html) goes into more detail about the feature.
+
+### Create curations [solutions-ecommerce-search-page-create-curations]
+
+Curations allow you to
+
+- promote some results to always show up at the top of the search results for a specific query
+- hide some results from showing up in the search results for a specific query
+
+Learn more about curations in our [Curations guide](https://www.elastic.co/guide/en/app-search/current/curations-guide.html)
+
+## Variants [solutions-ecommerce-search-page-variants]
+
+You might have several products that are essentially the same but have one different attribute. For example, it could be shirts of different colors. In our demo, it’s the same TV models but with different diagonal sizes.
+
+If you have such products in your store, consider combining them into a single result. That will prevents users from being overwhelmed by the number of options.
+
+:::{tip}
+[Try the demo in CodeSandbox](https://codesandbox.io/embed/github/elastic/search-ui/tree/main/examples/sandbox?autoresize=1&fontsize=12&initialpath=%2Fecommerce%2Fcategory%2FTVs&module=%2Fsrc%2Fpages%2Fecommerce%2Findex.jsx).
+:::
+
+To implement this in Search UI, you’ll need to do the following:
+
+1. Enrich your dataset.
+2. Enable grouping in Search UI config.
+3. Add variants rendering into your Result component.
+
+### Enriching dataset [solutions-ecommerce-search-page-enriching-dataset]
+
+Add a new field to all documents in your dataset that will be used for grouping search results. Here’s the example:
+
+```json
+[
+ {
+ "name": "Samsung TV 55 inch",
+ "product_group": "[GROUP_ID_1]"
+ },
+ {
+ "name": "Samsung TV 45 inch",
+ "product_group": "[GROUP_ID_1]"
+ },
+ {
+ "name": "LG TV 55 inch",
+ "product_group": "[GROUP_ID_2]"
+ }
+]
+```
+
+Make sure to add that new field to all the documents in a dataset! Otherwise, API will combine all the documents missing that field into a single group.
+
+### Enabling grouping in Search UI config [solutions-ecommerce-search-page-enabling-grouping-in-search-ui-config]
+
+Search UI does not directly support the grouping, but it is supported by the underlying [App Search API](https://www.elastic.co/guide/en/app-search/current/grouping.html). So instead of enabling it in the Search UI config, we’ll enable it in the App Search connector config. Here’s an example:
+
+```js
+const connector = new AppSearchAPIConnector({
+ searchKey: "search-key",
+ engineName: "engine-name",
+ endpointBase: "endpointBase",
+ // enabling grouping in App Search connector config
+ beforeSearchCall: (existingSearchOptions, next) =>
+ next({
+ ...existingSearchOptions,
+ group: { field: "product_group", collapse: true }
+ })
+});
+
+export const config = {
+ alwaysSearchOnInitialLoad: true,
+ apiConnector: connector
+ // other config properties
+};
+```
+
+### Adding variants rendering into your Result component [solutions-ecommerce-search-page-adding-variants-rendering-into-your-result-component]
+
+Once the grouping is enabled, the variants will be available via the `_group` field in your result document. Here’s a simplified example of how to use it:
+
+```jsx
+{
+ result._group && result._group.length > 0 && (
+
+ );
+}
+```
+
+## Sorting [solutions-ecommerce-search-page-sorting]
+
+% TO DO: Use `:class: screenshot`
+
+
+Adding sorting is simple — just use our `` component, like so:
+
+```js
+import { Sorting } from "@elastic/react-search-ui";
+
+;
+```
+
+A good starting point for sorting options is to have these three:
+
+- Relevance / Featured / Best Match (usually the default option)
+- Price: Low to High
+- Price: High to Low
+
+Consider adding some of these if they apply to your data:
+
+- Popularity
+- User rating
+- Distance (to the user)
+- Newest first
+
+:::{tip}
+Check out sorting in action in our [CodeSandbox demo](https://codesandbox.io/embed/github/elastic/search-ui/tree/main/examples/sandbox?autoresize=1&fontsize=12&initialpath=%2Fecommerce%2Fsearch&module=%2Fsrc%2Fpages%2Fecommerce%2Findex.jsx).
+:::
+
+## Related Articles [solutions-ecommerce-search-page-related-articles]
+
+- [Connectors API](/reference/api-connectors-app-search.md)
+- [Sorting](/reference/api-react-components-sorting.md)
+- [Creating Components](/reference/guides-creating-own-components.md): Build your own components for Search UI.
diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml
new file mode 100644
index 000000000..2429cf48c
--- /dev/null
+++ b/docs/reference/toc.yml
@@ -0,0 +1,62 @@
+toc:
+ - file: index.md
+ - file: ecommerce.md
+ children:
+ - file: solutions-ecommerce-autocomplete.md
+ - file: solutions-ecommerce-carousel.md
+ - file: solutions-ecommerce-category-page.md
+ - file: solutions-ecommerce-product-detail-page.md
+ - file: solutions-ecommerce-search-page.md
+ - file: tutorials.md
+ children:
+ - file: tutorials-elasticsearch.md
+ children:
+ - file: tutorials-elasticsearch-setup-cloud.md
+ - file: tutorials-elasticsearch-setup-index.md
+ - file: tutorials-elasticsearch-install-connector.md
+ - file: tutorials-elasticsearch-configure-search-ui.md
+ - file: tutorials-elasticsearch-production-usage.md
+ - file: tutorials-elasticsearch-customise-query.md
+ - file: tutorials-app-search.md
+ - file: tutorials-workplace-search.md
+ - file: basic-usage.md
+ children:
+ - file: guides-using-search-as-you-type.md
+ - file: guides-adding-search-bar-to-header.md
+ - file: guides-debugging.md
+ - file: advanced-usage.md
+ children:
+ - file: guides-conditional-facets.md
+ - file: guides-changing-component-behavior.md
+ - file: guides-analyzing-performance.md
+ - file: guides-creating-own-components.md
+ - file: guides-building-custom-connector.md
+ - file: guides-nextjs-integration.md
+ - file: api-reference.md
+ children:
+ - file: api-core-index.md
+ children:
+ - file: api-core-configuration.md
+ - file: api-core-state.md
+ - file: api-core-actions.md
+ - file: api-react-search-provider.md
+ children:
+ - file: api-react-with-search.md
+ - file: api-react-use-search.md
+ - file: api-react-components-search-box.md
+ children:
+ - file: api-react-components-results.md
+ - file: api-react-components-result.md
+ - file: api-react-components-results-per-page.md
+ - file: api-react-components-facet.md
+ - file: api-react-components-sorting.md
+ - file: api-react-components-paging.md
+ - file: api-react-components-paging-info.md
+ - file: api-react-components-error-boundary.md
+ - file: api-connectors-app-search.md
+ children:
+ - file: api-connectors-elasticsearch.md
+ - file: api-connectors-site-search.md
+ - file: api-connectors-workplace-search.md
+ - file: api-core-plugins-analytics-plugin.md
+ - file: known-issues.md
diff --git a/docs/tutorials-app-search.mdx b/docs/reference/tutorials-app-search.md
similarity index 70%
rename from docs/tutorials-app-search.mdx
rename to docs/reference/tutorials-app-search.md
index b2084aeac..451363cd5 100644
--- a/docs/tutorials-app-search.mdx
+++ b/docs/reference/tutorials-app-search.md
@@ -1,40 +1,52 @@
---
-id: tutorials-app-search
-slug: /search-ui/tutorials/app-search
-title: "Search UI with App Search"
-description: Build a search experience with App Search and Search UI
-date: 2022-04-13
-tags: ["Tutorial", "Parks", "US"]
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-app-search.html
+applies_to:
+ stack:
---
+# Search UI with App Search [tutorials-app-search]
+
+::::{admonition} Deprecation Notice
+:class: important
+
+App Search connector for Search UI is deprecated and will no longer be supported. Please migrate to [Elasticsearch Connector](/reference/api-connectors-elasticsearch.md) for continued support.
+
+::::
+
This tutorial will guide you through the process of creating a Search UI with [App Search](https://elastic.co/app-search), using the `search-ui-app-search-connector`. We will be using a sample engine in App Search, which comes pre-loaded with A US national parks dataset.
Within this tutorial, we assume that you have Node.js installed on your machine.
-## Setup App Search
+## Setup App Search [tutorials-app-search-setup-app-search]
First we need to setup App Search, which is a part of [Elastic Enterprise Search](https://elastic.co/enterprise-search). The easiest way to do this is to create a deployment on [Elastic Cloud](https://elastic.co/cloud). You can sign up for a free 14-day trial [here](https://cloud.elastic.co/register), no credit card required.
Once your deployment has been created, navigate to Enterprise Search in Kibana. You should be able to see a link to Enterprise Search from the home menu.
-
-
+% TO DO: Use `:class: screenshot`
+
+
+% TO DO: Use `:class: screenshot`
+
-In the next step, we'll navigate to App Search and create an engine that will hold our US national parks documents.
+In the next step, we’ll navigate to App Search and create an engine that will hold our US national parks documents.
-## Create an Engine with Sample Data
+## Create an Engine with Sample Data [tutorials-app-search-create-an-engine-with-sample-data]
-Select "Try a sample engine", which creates a engine loaded with useful sample data. The sample engine will be pre-loaded with the US national parks dataset that we'll need for our search experience. Easy!
+Select "Try a sample engine", which creates a engine loaded with useful sample data. The sample engine will be pre-loaded with the US national parks dataset that we’ll need for our search experience. Easy!
-
+% TO DO: Use `:class: screenshot`
+
-### Configure Schema
+### Configure Schema [tutorials-app-search-configure-schema]
-Once our sample engine has been created, the next step is to inspect our engine's schema. By default, App Search will choose the field type "text" for each field, but we can manually configure the field types to match the type of data each field represents — text, date, geolocation, or number. **For the sample engine, the fields have been pre-configured for us.**
+Once our sample engine has been created, the next step is to inspect our engine’s schema. By default, App Search will choose the field type "text" for each field, but we can manually configure the field types to match the type of data each field represents — text, date, geolocation, or number. **For the sample engine, the fields have been pre-configured for us.**
-
+% TO DO: Use `:class: screenshot`
+
-If you inspect the schema, you'll notice that a number of fields have been changed from their default `text` field type:
+If you inspect the schema, you’ll notice that a number of fields have been changed from their default `text` field type:
- `visitors` to be a **number**
- `square_km` to be a **number**
@@ -44,30 +56,31 @@ If you inspect the schema, you'll notice that a number of fields have been chang
Adjusting the field type allows us to use different queries, facets, and filters only applicable to the field types we are using. [Learn more about App Search schemas](https://www.elastic.co/guide/en/app-search/current/indexing-documents-guide.html#indexing-documents-guide-schema)
-### API Keys
+### API Keys [tutorials-app-search-api-keys]
API keys are used to access the engine. By default, there are two key types available:
- private-key: This is the key that is used to read and write to the engine.
- search-key: This is the key that has read only access to the engine.
-
+% TO DO: Use `:class: screenshot`
+
For this example, we are going to use the search-key. By default the search-key has been created. To use it, we must copy the key. Keep this key safe, we will be using it later on.
Also above is the host url. Copy this as we will use it later on as well.
-## Build a Search Experience with Search UI
+## Build a Search Experience with Search UI [tutorials-app-search-build-a-search-experience-with-search-ui]
For this tutorial, we are going to be using the popular [Create React App (CRA) framework](https://reactjs.org/docs/create-a-new-react-app.html). To get started, we run the following command
```shell
-npx create-react-app us-parks-demo
+ npx create-react-app us-parks-demo --template typescript
```
Once this has been completed, we can navigate to the directory of the project.
-### Install Search UI dependencies
+### Install Search UI dependencies [tutorials-app-search-install-search-ui-dependencies]
Now we need to install the dependencies for the search UI into our project. We can do this by running the following command:
@@ -77,11 +90,11 @@ yarn add @elastic/search-ui @elastic/react-search-ui-views @elastic/search-ui-ap
This will download the latest version of the packages and install them into our project.
-### Add Search UI React Components
+### Add Search UI React Components [tutorials-app-search-add-search-ui-react-components]
-We can now add the Search UI React components to our project. First we need to open `src/App.js` and replace it's contents with the following:
+We can now add the Search UI React components to our project. First we need to open `src/App.tsx` and replace it’s contents with the following:
-```js
+```jsx
import AppSearchAPIConnector from "@elastic/search-ui-app-search-connector";
import React from "react";
import {
@@ -93,7 +106,6 @@ import {
PagingInfo,
ResultsPerPage,
Paging,
- Sorting,
WithSearch
} from "@elastic/react-search-ui";
import {
@@ -103,6 +115,7 @@ import {
SingleSelectFacet
} from "@elastic/react-search-ui-views";
import "@elastic/react-search-ui-views/lib/styles/styles.css";
+import { SearchDriverOptions } from "@elastic/search-ui";
const connector = new AppSearchAPIConnector({
searchKey: "",
@@ -110,8 +123,7 @@ const connector = new AppSearchAPIConnector({
endpointBase: ""
});
-const config = {
- debug: true,
+const config: SearchDriverOptions = {
alwaysSearchOnInitialLoad: true,
apiConnector: connector,
hasA11yNotifications: true,
@@ -166,7 +178,7 @@ export default function App() {
}
```
-Before we can run our app, we'll have to do some initial configuration. To start, let's add our deployment details to the `connector` configuration. Replace `` with your deployment's public search key and replace `` with your deployment's endpoint URL.
+Before we can run our app, we’ll have to do some initial configuration. To start, let’s add our deployment details to the `connector` configuration. Replace `` with your deployment’s public search key and replace `` with your deployment’s endpoint URL.
```jsx
const connector = new AppSearchAPIConnector({
@@ -176,7 +188,7 @@ const connector = new AppSearchAPIConnector({
});
```
-Next, we'll have to add at least one field to `search_fields` within the `config` object, otherwise Search UI won't be able to successfully execute a query. Let's start by adding the `title` field:
+Next, we’ll have to add at least one field to `search_fields` within the `config` object, otherwise Search UI won’t be able to successfully execute a query. Let’s start by adding the `title` field:
```jsx
search_fields: {
@@ -192,13 +204,14 @@ yarn start
You should now have a working, basic search experience that looks similar to the example below:
-
+% TO DO: Use `:class: screenshot`
+
-## Configure Search UI
+## Configure Search UI [tutorials-app-search-configure-search-ui]
We now have a working search experience, but we need to configure it now to take advantage of the data we have. Lets start by identifying which fields we want to search, display, and make available as facets.
-Here's an example document from the data that we have indexed:
+Here’s an example document from the data that we have indexed:
```json
{
@@ -222,9 +235,9 @@ Based on this document, we can determine the fields that we want to be:
- **Displayable**: title, description, states, visitors, acres, square_km, date_established, nps_link
- **Facetable**: states, visitors, acres, square_km, date_established
-### Searchable Configuration
+### Searchable Configuration [tutorials-app-search-searchable-configuration]
-In a previous step we added the `title` to `search_fields`, but we'll expand on that here. For our complete search experience, we want `title`, `description`, and `states` to be searchable. We can do this by adding the following to the `config` object:
+In a previous step we added the `title` to `search_fields`, but we’ll expand on that here. For our complete search experience, we want `title`, `description`, and `states` to be searchable. We can do this by adding the following to the `config` object:
```js
search_fields: {
@@ -238,7 +251,7 @@ search_fields: {
The `weight` parameter that we added to `title` is the weight of the field. The higher the weight, the more important the field is when relevance is calculated. [Learn more about relevance tuning](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html)
-### Displayble Configuration
+### Displayble Configuration [tutorials-app-search-displayble-configuration]
We want `title`, `description`, `states`, `visitors`, `acres`, `square_km`, `nps_link` and `date_established` to be displayable, or usable in our search results. We can do this by adding the following to the `config` object:
@@ -269,7 +282,7 @@ result_fields: {
`snippet` is a configuration for the display of the field. Any value that matches a field will be displayed in the results as a highlight. The `fallback` will be used if a highlight is not found. [Learn more about result settings](https://www.elastic.co/guide/en/app-search/current/result-settings-guide.html)
-### Facetable Configuration
+### Facetable Configuration [tutorials-app-search-facetable-configuration]
We want `states`, `visitors`, `acres`, `square_km`, and `date_established` to be facetable. We can do this by adding the following to the `config` object:
@@ -338,7 +351,7 @@ The example above shows a variety of facet types, including:
[Learn more about facets](https://www.elastic.co/guide/en/app-search/current/facets-guide.html)
-For these facets to appear, we need to add the facet components to our view. Let's replace the `sideContent` prop in our view with the example below:
+For these facets to appear, we need to add the facet components to our view. Let’s replace the `sideContent` prop in our view with the example below:
```jsx
sideContent={
@@ -346,7 +359,6 @@ sideContent={
+```
+
+## Test Drive! [tutorials-app-search-test-drive]
You should be able to see the results of your search like below:
-
+% TO DO: Use `:class: screenshot`
+
-## Next Steps
+## Next Steps [tutorials-app-search-next-steps]
Lets recap of the steps we have covered:
- We created an App Search Engine and indexed a sample data set of us-parks
-- We configured the engine's schema and fields
+- We configured the engine’s schema and fields
- We created a new React project and added the Search UI components
- We configured the search UI to search the engine and display facets to help the user narrow down the results
-Next you can add more data into the index, , and deploy the app.
+Next you can add more data into the index, [update the results view to display more fields](/reference/api-react-components-result.md#api-react-components-result-view-customization), and deploy the app.
diff --git a/docs/reference/tutorials-elasticsearch-configure-search-ui.md b/docs/reference/tutorials-elasticsearch-configure-search-ui.md
new file mode 100644
index 000000000..f1717c1da
--- /dev/null
+++ b/docs/reference/tutorials-elasticsearch-configure-search-ui.md
@@ -0,0 +1,185 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-elasticsearch-configure-search-ui.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Configure and Run Search UI [tutorials-elasticsearch-configure-search-ui-and-run]
+
+## Configure Search UI [tutorials-elasticsearch-step-5-configure-search-ui]
+
+Next lets configure Search UI for our needs! Navigate to the config within app.js and update the following:
+
+```js
+const config = {
+ searchQuery: {
+ search_fields: {
+ title: {
+ weight: 3
+ },
+ plot: {},
+ genre: {},
+ actors: {},
+ directors: {}
+ },
+ result_fields: {
+ title: {
+ snippet: {}
+ },
+ plot: {
+ snippet: {}
+ }
+ },
+ disjunctiveFacets: ["genre.keyword", "actors.keyword", "directors.keyword"],
+ facets: {
+ "genre.keyword": { type: "value" },
+ "actors.keyword": { type: "value" },
+ "directors.keyword": { type: "value" },
+ released: {
+ type: "range",
+ ranges: [
+ {
+ from: "2012-04-07T14:40:04.821Z",
+ name: "Within the last 10 years"
+ },
+ {
+ from: "1962-04-07T14:40:04.821Z",
+ to: "2012-04-07T14:40:04.821Z",
+ name: "10 - 50 years ago"
+ },
+ {
+ to: "1962-04-07T14:40:04.821Z",
+ name: "More than 50 years ago"
+ }
+ ]
+ },
+ imdbRating: {
+ type: "range",
+ ranges: [
+ { from: 1, to: 3, name: "Pants" },
+ { from: 3, to: 6, name: "Mediocre" },
+ { from: 6, to: 8, name: "Pretty Good" },
+ { from: 8, to: 10, name: "Excellent" }
+ ]
+ }
+ }
+ },
+ autocompleteQuery: {
+ results: {
+ resultsPerPage: 5,
+ search_fields: {
+ "title.suggest": {
+ weight: 3
+ }
+ },
+ result_fields: {
+ title: {
+ snippet: {
+ size: 100,
+ fallback: true
+ }
+ },
+ url: {
+ raw: {}
+ }
+ }
+ },
+ suggestions: {
+ types: {
+ results: { fields: ["movie_completion"] }
+ },
+ size: 4
+ }
+ },
+ apiConnector: connector,
+ alwaysSearchOnInitialLoad: true
+};
+```
+
+In the above example, we configured the:
+
+- query fields to search on title, plot, genre, actors and directors using the text fields
+- result fields to display title, plot, genre, actors and directors using the text fields
+- facets to display genre, actors and directors using the keyword fields
+- we made the facets disjunctive for better user experience. The user can select more than one facet to expand their search.
+- autocomplete results to suggest results with the same query fields as main search + returning some fields for display.
+
+For more information on configuration, visit the [API configuration docs](/reference/api-core-configuration.md).
+
+## Updating Components [tutorials-elasticsearch-updating-components]
+
+We are going to do several steps here:
+
+- update the `` component to configure autocomplete
+- remove sorting options
+- add a `` component for each facet field
+- update the `` component to display all the fields
+
+```jsx
+
+```
+
+## Run [tutorials-elasticsearch-step-6-test-drive]
+
+Lets run the project with the command:
+
+```shell
+yarn start
+```
+
+and then view the results in the browser at [http://localhost:3000/](http://localhost:3000/)
+
+% TO DO: Use `:class: screenshot`
+
+
+## Summary [tutorials-elasticsearch-next-steps]
+
+Lets recap of the steps we have covered:
+
+- we setup and configured the Elasticsearch index for our data
+- we indexed an example movie
+- we checked out the starter app and added the Elasticsearch connector
+- we configured the Elasticsearch connector to connect to our Elasticsearch index
+- we updated the Search UI configuration to specify the fields to be searchable, facetable
+- we updated the components to use these fields
+
+Next you can add more data into the index, [update the results view to display more fields](/reference/api-react-components-result.md#api-react-components-result-view-customization), and deploy the app.
diff --git a/docs/reference/tutorials-elasticsearch-customise-query.md b/docs/reference/tutorials-elasticsearch-customise-query.md
new file mode 100644
index 000000000..2abc742bb
--- /dev/null
+++ b/docs/reference/tutorials-elasticsearch-customise-query.md
@@ -0,0 +1,79 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-elasticsearch-customise-request.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Customise Request [api-connectors-elasticsearch-customise-the-elasticsearch-request-body]
+
+Elasticsearch connector allows you to customise the Elasticsearch request body before its performed on Elasticsearch. This is useful if you want to customise the query or options before the request is sent to Elasticsearch.
+
+This is an advanced option, the underlying query may change between versions and reading from / mutating the query is brittle, so please be aware to use this sparingly and let us know what you want to achieve through github issues.
+
+## Using interceptSearchRequest Hook
+
+The `interceptSearchRequest` hook allows you to modify the entire request body before it's sent to Elasticsearch. This is useful when you need to modify multiple parts of the request or add custom fields.
+
+```js
+const connector = new ElasticsearchAPIConnector({
+ host: "https://example-host.es.us-central1.gcp.cloud.es.io:9243",
+ index: "national-parks",
+ apiKey: "exampleApiKey",
+ interceptSearchRequest: async (
+ { requestBody, requestState, queryConfig },
+ next
+ ) => {
+ console.log("Search request:", requestBody); // logging out the requestBody before sending to Elasticsearch
+
+ if (!requestState.searchTerm) {
+ return next(requestBody);
+ }
+
+ const searchFields = queryConfig.search_fields;
+ const modifiedBody = {
+ ...requestBody,
+ query: {
+ multi_match: {
+ query: requestState.searchTerm,
+ fields: Object.keys(searchFields).map((fieldName) => {
+ const weight = searchFields[fieldName].weight || 1;
+ return `${fieldName}^${weight}`;
+ })
+ }
+ }
+ };
+
+ return next(modifiedBody);
+ }
+});
+```
+
+The hook receives the current request state and configuration, allowing you to modify the request before it's sent to Elasticsearch. Always call `next()` with the modified request body to ensure the request is sent to Elasticsearch.
+
+## Using getQueryFn Hook
+
+The `getQueryFn` hook allows you to completely override the query generation. This is useful when you want to implement custom query logic or use advanced Elasticsearch features like semantic search. The hook is called only when there is a search query, so you don't need to handle empty search terms.
+
+```js
+const connector = new ElasticsearchAPIConnector({
+ host: "https://example-host.es.us-central1.gcp.cloud.es.io:9243",
+ index: "national-parks",
+ apiKey: "exampleApiKey",
+ getQueryFn: (state, config) => ({
+ semantic: {
+ field: "inference_field",
+ query: state.searchTerm
+ }
+ })
+});
+```
+
+The `getQueryFn` hook only replaces the query part of the request body. Filters are still added separately and automatically mixed in. This makes it perfect for implementing custom search algorithms while maintaining compatibility with Search UI's filtering system.
+
+::::{admonition} Note
+:class: important
+
+This example uses Elasticsearch's built-in semantic search. Make sure you have configured the inference pipeline and the field is properly mapped in your index. See [Semantic Search](https://www.elastic.co/docs/solutions/search/semantic-search) documentation for setup instructions.
+::::
diff --git a/docs/reference/tutorials-elasticsearch-install-connector.md b/docs/reference/tutorials-elasticsearch-install-connector.md
new file mode 100644
index 000000000..8db1e7c82
--- /dev/null
+++ b/docs/reference/tutorials-elasticsearch-install-connector.md
@@ -0,0 +1,71 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-elasticsearch-install-connector.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Install Connector [tutorials-elasticsearch-installing-connector]
+
+### Setup CRA for Search UI [tutorials-elasticsearch-step-4-setup-cra-for-search-ui]
+
+First, download the Search-UI’s starter app from github by
+
+```shell
+curl https://codeload.github.com/elastic/app-search-reference-ui-react/tar.gz/master | tar -xz
+```
+
+and should appear as a folder called `app-search-reference-ui-react-main`.
+
+Navigate to the root to the folder and install the dependencies using the following command:
+
+```shell
+yarn
+```
+
+## Installing сonnector [tutorials-elasticsearch-installing-connector]
+
+Within the folder, we can now install the `@elastic/search-ui-elasticsearch-connector` library with Yarn.
+
+```shell
+yarn add @elastic/search-ui-elasticsearch-connector
+```
+
+Make sure to check and update Search UI dependencies to the latest version. You can find the latest version by going to [NPM’s page for @elastic/search-ui](https://www.npmjs.com/package/@elastic/search-ui).
+
+## Setting up the connector [tutorials-elasticsearch-setting-up-the-connector]
+
+Open the project within your favorite editor.
+
+Within `src/App.js`, change line 3 to import the Elasticsearch connector. You no longer need the app-search connector.
+
+```js
+import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";
+```
+
+and then update the options to the connector
+
+```js
+const connector = new ElasticsearchAPIConnector({
+ cloud: {
+ id: ""
+ },
+ apiKey: "",
+ index: "my-example-movies"
+});
+```
+
+If you’re using Elastic Cloud, you can find your cloud id within your deployment’s details.
+
+% TO DO: Use `:class: screenshot`
+
+
+alternatively, if you’re using an on-premise Elasticsearch instance, you can connect via specifying the host.
+
+```js
+const connector = new ElasticsearchAPIConnector({
+ host: "http://localhost:9200",
+ index: "my-example-movies"
+});
+```
diff --git a/docs/reference/tutorials-elasticsearch-production-usage.md b/docs/reference/tutorials-elasticsearch-production-usage.md
new file mode 100644
index 000000000..0f21ddff1
--- /dev/null
+++ b/docs/reference/tutorials-elasticsearch-production-usage.md
@@ -0,0 +1,103 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-elasticsearch-production-usage.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Using in Production [tutorials-elasticsearch-production-usage]
+
+In production, it's **strongly recommended** not to expose your Elasticsearch instance directly to the browser. Instead, proxy all requests through your own backend server.
+
+## Connection & Authentication [api-connectors-elasticsearch-connection-and-authentication]
+
+You have the following options available to you for securely exposing your Elasticsearch instance to the internet:
+
+### Proxying Elasticsearch Requests [api-connectors-elasticsearch-proxy-the-_search-api-call-through-your-api]
+
+:::{tip}
+This is the **recommended** approach and will be used in the examples below.
+:::
+
+This involves creating an API route that proxies search requests to Elasticsearch. Proxying enables you to:
+
+- Add custom headers or API keys on the server.
+- Apply filters to restrict access to specific documents
+- Your own user based authentication for your API
+- Monitor and log search activity
+- Add a caching layer between the API and Elasticsearch
+
+Use `ApiProxyConnector` in the frontend to send requests to your backend, and `ElasticsearchAPIConnector` in the backend to forward them to Elasticsearch.
+
+### API Key Restrictions [api-connectors-elasticsearch-use-an-elasticsearch-api-key]
+
+You can restrict access to indices by using an API key. We **recommend** you create an apiKey that is restricted to the particular index and has **read-only** authorization. See [Kibana API keys guide](docs-content://deploy-manage/api-keys/elasticsearch-api-keys.md). To use the API key, place it within the Elasticsearch connection configuration.
+
+## Frontend Update [tutorials-elasticsearch-production-usage-client]
+
+To proxy search requests through your server, use the `ApiProxyConnector`. This connector sends search and autocomplete requests to your backend, where the real Elasticsearch query is executed.
+
+```js
+import { ApiProxyConnector } from "@elastic/search-ui-elasticsearch-connector/api-proxy";
+const connector = new ApiProxyConnector({
+ basePath: "http://localhost:3001/api" // ⚠️ Replace with your server URL in production
+ // fetchOptions: {} // Optional: Add headers or credentials here if needed
+});
+
+const config = {
+ apiConnector: connector
+ // other Search UI config options
+};
+```
+
+For more details, see the [ApiProxyConnector](/reference/api-connectors-elasticsearch.md#api-connectors-elasticsearch-api-proxy-doc-reference)
+
+## Server Usage [tutorials-elasticsearch-production-usage-server]
+
+On your backend, handle the request using `ElasticsearchAPIConnector` and pass in the request body from the client:
+
+```js
+import express from "express";
+import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";
+
+const app = express();
+app.use(express.json());
+
+const connector = new ElasticsearchAPIConnector({
+ host: "https://your-elasticsearch-host", // ⚠️ Replace with your Elasticsearch host
+ index: "your-index", // ✅ Use the same index as your data
+ apiKey: "your-api-key" // 🔒 Use a secure, read-only API key
+});
+
+app.post("/api/search", async (req, res) => {
+ const { state, queryConfig } = req.body; // { state: RequestState, queryConfig: QueryConfig } - comes from ApiProxyConnector on the frontend
+ 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);
+```
+
+For other authentication methods, check the [Elasticsearch API connector reference](/reference/api-connectors-elasticsearch.md#api-connectors-elasticsearch-doc-reference).
+
+## Summary [tutorials-elasticsearch-production-usage-summary]
+
+For a secure and scalable production setup:
+
+- Use `ApiProxyConnector` on the frontend.
+- Use `ElasticsearchAPIConnector` on the server.
+- **Avoid to** expose your Elasticsearch API key to the browser.
+- Monitor and log if needed.
+
+:::{tip}
+You can explore a **production ready** example using this setup in our [CodeSandbox](https://codesandbox.io/p/sandbox/github/elastic/search-ui/tree/main/examples/sandbox?file=/src/pages/elasticsearch-production-ready/index.jsx).
+
+It demonstrates how to use `ApiProxyConnector` on the client and proxy search requests to a backend that uses `ElasticsearchAPIConnector`.
+:::
diff --git a/docs/reference/tutorials-elasticsearch-setup-cloud.md b/docs/reference/tutorials-elasticsearch-setup-cloud.md
new file mode 100644
index 000000000..16e4641a4
--- /dev/null
+++ b/docs/reference/tutorials-elasticsearch-setup-cloud.md
@@ -0,0 +1,64 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-elasticsearch-setup-cloud.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Setup Elasticsearch [tutorials-elasticsearch-step-1-setup-elasticsearch]
+
+First we need to setup Elasticsearch. The easiest way to do this is to create an Elasticsearch instance via [Elastic Cloud](https://cloud.elastic.co/registration).
+
+## Setting up a read-only API Key [tutorials-elasticsearch-setting-up-a-read-only-api-key]
+
+Next we need to setup an API key to access the data from the index. We can do this via Kibana’s Stack Management API Keys page (`/app/management/security/api_keys`). Note that security needs to be enabled for this option to be available.
+
+Notice here we are only giving read privileges for this api key. You will need to setup an api key with write privileges to add and update data to the index.
+
+```json
+{
+ "superuser": {
+ "cluster": ["all"],
+ "indices": [
+ {
+ "names": ["my-example-movies"],
+ "privileges": ["read"],
+ "allow_restricted_indices": false
+ }
+ ]
+ }
+}
+```
+
+% TO DO: Use `:class: screenshot`
+
+
+Once saved, you are presented with the api-key. Copy this and keep it safe. We will need to use this further down in the tutorial.
+
+% TO DO: Use `:class: screenshot`
+
+
+## Enabling CORS [tutorials-elasticsearch-enabling-cors]
+
+If you’re going to be accessing Elasticsearch directly from a browser and the Elasticsearch host domain doesn’t match your site’s domain, you will need to enable CORS.
+
+CORS is a browser mechanism which enables controlled access to resources located outside of the current domain. In order for the browser to make requests to Elasticsearch, CORS configuration headers need to specified in the Elasticsearch configuration.
+
+% TO DO: Use `:class: screenshot`
+
+
+You can do this in cloud by going to the deployment settings for your Elasticsearch instance, click "Edit user settings and plugins" and under "user settings", add the CORS configuration below:
+
+```yaml
+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
+```
+
+% TO DO: Use `:class: screenshot`
+
+
+then save. Your Elasticsearch instance will be restarted and the CORS configuration will be active.
diff --git a/docs/reference/tutorials-elasticsearch-setup-index.md b/docs/reference/tutorials-elasticsearch-setup-index.md
new file mode 100644
index 000000000..44106afd4
--- /dev/null
+++ b/docs/reference/tutorials-elasticsearch-setup-index.md
@@ -0,0 +1,196 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-elasticsearch-setup-index.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Setup an Index [tutorials-elasticsearch-setting-up-an-index]
+
+We are going to issue commands via [Kibana’s dev tools console](docs-content://explore-analyze/query-filter/tools/console.md). You can alternatively use a REST client like Postman to achieve this.
+
+First we need to create an index for our data. We can do this simply via the following request:
+
+```shell
+PUT /my-example-movies
+```
+
+% TO DO: Use `:class: screenshot`
+
+
+Elasticsearch will acknowledge our request in the response.
+
+## Mapping Examples [tutorials-elasticsearch-examples]
+
+Next we need to setup the index fields, ready for us to ingest data.
+
+The [mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html) for an index depends on the data you want to index and the features you want.
+
+### Searchable Fields [tutorials-elasticsearch-setting-up-an-index-examples-searchable]
+
+We want to be able to search on title. We need only one field of type text.
+
+```json
+{
+ "properties": {
+ "title": {
+ "type": "text"
+ }
+ }
+}
+```
+
+### Searchable and Filterable Fields [tutorials-elasticsearch-setting-up-an-index-filterable]
+
+We want to be able to search and product facets for writers field. We need two fields of different types: keyword and text.
+
+```json
+{
+ "properties": {
+ "writers": {
+ "type": "text",
+ "fields": {
+ "keyword": {
+ "type": "keyword"
+ }
+ }
+ }
+ }
+}
+```
+
+### Date fields for Facets [tutorials-elasticsearch-setting-up-an-index-date-facet]
+
+We want to be able to filter on a date field. We only need one date field.
+
+```json
+{
+ "properties": {
+ "released": {
+ "type": "date"
+ }
+ }
+}
+```
+
+### Numerical fields for Facets [tutorials-elasticsearch-setting-up-an-index-numeric]
+
+We want to be able to filter on a numeric field. We only need one numeric field. Can be a choice of integer, float and [more documented here](elasticsearch://reference/elasticsearch/mapping-reference/number.md)
+
+```json
+{
+ "properties": {
+ "imdbRating": {
+ "type": "float"
+ }
+ }
+}
+```
+
+## Index Movies Mapping [tutorials-elasticsearch-settion-up-an-index-movies-mapping]
+
+For our movie data-set, we will be using the following fields:
+
+- title (searchable)
+- plot (searchable)
+- genre (searchable, facetable)
+- actors (searchable, facetable)
+- directors (searchable, facetable)
+- released (filterable)
+- imdbRating (filterable)
+- url
+
+The mapping file will be as follows, and we’ll once again use Kibana’s dev tools console to update the mapping file for our index.
+
+```shell
+PUT /my-example-movies/_mapping
+{
+ "properties": {
+ "title": {
+ "type": "text",
+ "fields": {
+ "suggest": {
+ "type": "search_as_you_type"
+ }
+ }
+ },
+ "plot": {
+ "type": "text"
+ },
+ "genre": {
+ "type": "text",
+ "fields": {
+ "keyword": {
+ "type": "keyword"
+ }
+ }
+ },
+ "actors": {
+ "type": "text",
+ "fields": {
+ "keyword": {
+ "type": "keyword"
+ }
+ }
+ },
+ "directors": {
+ "type": "text",
+ "fields": {
+ "keyword": {
+ "type": "keyword"
+ }
+ }
+ },
+ "released": {
+ "type": "date"
+ },
+ "imdbRating": {
+ "type": "float"
+ },
+ "url": {
+ "type": "keyword"
+ },
+ "movie_completion": {
+ "type": "completion"
+ }
+ }
+}
+```
+
+% TO DO: Use `:class: screenshot`
+
+
+Elasticsearch will acknowledge the request in the response.
+
+We also want to provide autocomplete functionality, so we need to setup fields for autocomplete.
+
+For suggestions, we want to suggest terms that appear within the actors, directors and genre fields. For quick result hits, we want to suggest movies that partially match the title field.
+
+In the above example:
+
+- we have included `movie_completion` field, which is used to provide suggestion completion functionality. This field is not searchable, but is used to provide autocomplete functionality.
+- we have included a `suggest` field for the title field. This field is searchable, but is used to provide "quick hits" functionality.
+
+## Index Movies Data [tutorials-elasticsearch-step-3-index-movies-data]
+
+Now with our index and mapping file created, we are ready to index some data! We will use the bulk API to index our data.
+
+We will use the following request. In this example we will be indexing the first movie in the data-set to verify that the data fields is being indexed correctly.
+
+```shell
+PUT /my-example-movies/_bulk
+{ "index": {}}
+{
+ "title": "The Godfather",
+ "released": "1972-03-23T23:00:00.000Z",
+ "genre": ["Crime", "Drama"],
+ "directors": ["Francis Ford Coppola"],
+ "actors": ["Marlon Brando", "Al Pacino", "James Caan", "Richard S. Castellano"],
+ "plot": "The aging patriarch of an organized crime dynasty transfers control of his clandestine empire to his reluctant son","imdbRating": "9.2",
+ "movie_completion": ["Crime", "Drama", "Marlon Brando", "Al Pacino", "James Caan", "Richard S. Castellano"],
+ "url": "https://www.imdb.com/title/tt0068646/"
+}
+```
+
+Your Elasticsearch instance is now ready to be used.
diff --git a/docs/reference/tutorials-elasticsearch.md b/docs/reference/tutorials-elasticsearch.md
new file mode 100644
index 000000000..1725495af
--- /dev/null
+++ b/docs/reference/tutorials-elasticsearch.md
@@ -0,0 +1,44 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-elasticsearch.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Search UI with Elasticsearch [tutorials-elasticsearch]
+
+This section provides step-by-step guides and examples to help you build a modern search experience using Search UI and Elasticsearch.
+
+Whether you're just starting out or preparing for production, you'll find the right guide here.
+
+## Getting Started
+
+Learn how to create a working search interface from scratch:
+
+- [Setup Elasticsearch](/reference/tutorials-elasticsearch-setup-cloud.md)
+- [Create and map an index](/reference/tutorials-elasticsearch-setup-index.md)
+- [Install connector](/reference/tutorials-elasticsearch-install-connector.md)
+- [Configure and run Search UI](/reference/tutorials-elasticsearch-configure-search-ui.md)
+- [Customise Request](/reference/tutorials-elasticsearch-customise-query.md)
+
+## Production Usage
+
+Best practices for deploying Search UI in production:
+
+- [Using in Production](/reference/tutorials-elasticsearch-production-usage.md)
+
+## Sandbox Examples
+
+Want to explore live code examples? Check out our [CodeSandbox](https://codesandbox.io/p/sandbox/github/elastic/search-ui/tree/main/examples/sandbox) with ready-to-run setups:
+
+- Basic Elasticsearch connector
+- Server-proxied setup for production
+- Use cases & API examples
+
+## Reference Docs
+
+For advanced configuration and full API details, see:
+
+- [Elasticsearch Connector API Reference](/reference/api-connectors-elasticsearch.md)
+- [Search UI Core Configuration](/reference/api-core-configuration.md)
diff --git a/docs/tutorials-workplace-search.mdx b/docs/reference/tutorials-workplace-search.md
similarity index 67%
rename from docs/tutorials-workplace-search.mdx
rename to docs/reference/tutorials-workplace-search.md
index 1984df690..214835e91 100644
--- a/docs/tutorials-workplace-search.mdx
+++ b/docs/reference/tutorials-workplace-search.md
@@ -1,21 +1,24 @@
---
-id: tutorials-workplace-search
-slug: /search-ui/tutorials/workplace-search
-title: Workplace Search
-date: 2022-04-18
-tags: ["demo"]
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-workplace-search.html
+applies_to:
+ stack:
---
-
- Workplace Search connector for Search UI is currently in technical preview
- status. It is not ready for production use.
-
+# Search UI with Workplace Search [tutorials-workplace-search]
+
+::::{admonition} Deprecation Notice
+:class: important
+
+Workplace Search connector for Search UI is deprecated and will no longer be supported. Please migrate to [Elasticsearch Connector](/reference/api-connectors-elasticsearch.md) for continued support.
+
+::::
This guide will walk you through getting up and running with a Search UI using [Elastic Workplace Search](https://www.elastic.co/workplace-search/) as a backend.
-Have problems with the setup? Let us know in the [feedback issue](https://github.com/elastic/search-ui/issues/707), and we'll try to help.
+Have problems with the setup? Let us know in the [feedback issue](https://github.com/elastic/search-ui/issues/707), and we’ll try to help.
-## Prerequisites
+## Prerequisites [tutorials-workplace-search-prerequisites]
Before continuing with this guide, make sure you:
@@ -26,13 +29,13 @@ The best way to get started with Elastic Workplace Search is to follow our [Gett
To index data into Workplace Search, read the [Content Sources Overview](https://www.elastic.co/guide/en/workplace-search/current/workplace-search-content-sources.html) and follow a guide for any content source available there.
-## Creating a search page
+## Creating a search page [tutorials-workplace-search-creating-a-search-page]
-Have you indexed data into Workplace Search? Great! Let's create a search page in your application.
+Have you indexed data into Workplace Search? Great! Let’s create a search page in your application.
-We'll use React components in this tutorial, but you can use Search UI with any UI framework and even vanilla JavaScript. Read our to learn more about using Search UI outside of React.
+We’ll use React components in this tutorial, but you can use Search UI with any UI framework and even vanilla JavaScript. Read about our [API reference](/reference/api-reference.md) to learn more about using Search UI outside of React.
-First, let's install Search UI packages:
+First, let’s install Search UI packages:
```shell
npm install @elastic/react-search-ui @elastic/search-ui-workplace-search-connector
@@ -97,26 +100,27 @@ export default function WorkplaceSearch() {
}
```
-This page shouldn't work yet. To connect to the Workplace Search backend, you need to provide some details in the connector configuration.
+This page shouldn’t work yet. To connect to the Workplace Search backend, you need to provide some details in the connector configuration.
-## Adding connector configuration
+## Adding connector configuration [tutorials-workplace-search-adding-connector-configuration]
-Here's where to get the required configuration parameters:
+Here’s where to get the required configuration parameters:
-### `kibanaBase` and `enterpriseSearchBase`
+### `kibanaBase` and `enterpriseSearchBase` [tutorials-workplace-search-kibanabase-and-enterprisesearchbase]
You can get both values on the API Keys page in Workplace Search:
- `kibanaBase` — from the url,
- `enterpriseSearchBase` — from the Endpoint panel.
-
+% TO DO: Use `:class: screenshot`
+
-### `redirectUri`
+### `redirectUri` [tutorials-workplace-search-redirecturi]
Use the path to the page where Search UI is going to live.
-### `clientId`
+### `clientId` [tutorials-workplace-search-clientid]
To get a clientId, you need to create a new OAuth application in Workplace Search.
@@ -126,7 +130,8 @@ To get a clientId, you need to create a new OAuth application in Workplace Searc
4. Save changes.
5. Copy the `Client id` from the Credentials section.
-
+% TO DO: Use `:class: screenshot`
+
After finishing these steps, you should have a configuration that looks something like this:
@@ -141,21 +146,23 @@ const connector = new WorkplaceSearchAPIConnector({
});
```
-## Authorizing the application
+## Authorizing the application [tutorials-workplace-search-authorizing-the-application]
You should now be able to authorize.
Click on the "Log in" link in the Search UI and authorize the application to search your data.
-
+% TO DO: Use `:class: screenshot`
+
Once you click the Authorize button, you should be redirected back to your application and see the search results.
-
+% TO DO: Use `:class: screenshot`
+
Congratulations! You have successfully connected to Workplace Search.
-## Next steps
+## Next steps [tutorials-workplace-search-next-steps]
The UI we have now is very minimal. That is intentional to get you started quickly.
diff --git a/docs/reference/tutorials.md b/docs/reference/tutorials.md
new file mode 100644
index 000000000..f87b803e8
--- /dev/null
+++ b/docs/reference/tutorials.md
@@ -0,0 +1,25 @@
+---
+navigation_title: "Tutorials"
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/tutorials-connectors.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# Which connector to choose? [tutorials-connectors]
+
+The first thing you want to consider before implementing your search is the backend you’re going to use for your data.
+
+- (Recommended) [Elasticsearch Connector](/reference/api-connectors-elasticsearch.md) is the best option for working with [Elasticsearch](https://www.elastic.co/elasticsearch). It’s a flexible option that gives you full control over the request and response flow — but it can also work out of the box with minimal configuration.
+- [Site Search](/reference/api-connectors-site-search.md) if you are already using [Swiftype](https://swiftype.com/), these are basically a single product with two names.
+- Use [Custom Connector Guide](/reference/guides-building-custom-connector.md) if none of the built-in connectors fit your use case.
+
+### ⚠️ Deprecated connectors
+
+The following connectors are no longer recommended for use in new projects:
+
+- [Elastic App Search](/reference/api-connectors-app-search.md)
+- [Elastic Workplace Search](/reference/api-connectors-workplace-search.md)
+
+These products are deprecated and not actively maintained. If you’re still using them, the connectors will technically work — but we suggest migrating to the [Elasticsearch Connector](/reference/api-connectors-elasticsearch.md).
diff --git a/docs/tutorials-elasticsearch.mdx b/docs/tutorials-elasticsearch.mdx
deleted file mode 100644
index 0365181bf..000000000
--- a/docs/tutorials-elasticsearch.mdx
+++ /dev/null
@@ -1,464 +0,0 @@
----
-id: tutorials-elasticsearch
-slug: /search-ui/tutorials/elasticsearch
-title: "Search UI with Elasticsearch"
-description: Build a search experience with Elasticsearch and Search UI
-date: 2022-04-13
-tags: ["Tutorial", "Elasticsearch", "movies"]
----
-
-
- Elasticsearch connector for Search UI is currently in technical preview
- status. It is not ready for production use.
-
-
-This tutorial will guide you through the process of creating a Search UI with Elasticsearch directly, using the `elasticsearch-connector`. We will be using a sample movie data-set of around 1000 movies.
-
-Within this tutorial, we assume that you have Node.js installed on your machine.
-
-## Step 1: Setup Elasticsearch
-
-First we need to setup Elasticsearch. The easiest way to do this is to create an Elasticsearch instance via [Elastic Cloud](https://cloud.elastic.co/registration).
-
-### Setting up an Index
-
-We are going to issue commands via [Kibana's dev tools console](https://www.elastic.co/guide/en/kibana/current/console-kibana.html). You can alternatively use a REST client like Postman to achieve this.
-
-First we need to create an index for our data. We can do this simply via the following request:
-
-```shell
-PUT /my-example-movies
-```
-
-
-
-Elasticsearch will acknowledge our request in the response.
-
-### Setting up a read-only API Key
-
-Next we need to setup an API key to access the data from the index. We can do this via Kibana's Stack Management API Keys page (`/app/management/security/api_keys`). Note that security needs to be enabled for this option to be available.
-
-Notice here we are only giving read privileges for this api key. You will need to setup an api key with write privileges to add and update data to the index.
-
-```json
-{
- "superuser": {
- "cluster": ["all"],
- "indices": [
- {
- "names": ["my-example-movies"],
- "privileges": ["read"],
- "allow_restricted_indices": false
- }
- ]
- }
-}
-```
-
-
-
-Once saved, you are presented with the api-key. Copy this and keep it safe. We will need to use this further down in the tutorial.
-
-
-
-### Enabling CORS
-
-If you're going to be accessing Elasticsearch directly from a browser and the Elasticsearch host domain doesn't match your site's domain, you will need to enable CORS.
-
-CORS is a browser mechanism which enables controlled access to resources located outside of the current domain. In order for the browser to make requests to Elasticsearch, CORS configuration headers need to specified in the Elasticsearch configuration.
-
-
-
-You can do this in cloud by going to the deployment settings for your Elasticsearch instance, click "Edit user settings and plugins" and under "user settings", add the CORS configuration below:
-
-```yaml
-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
-```
-
-
-
-then save. Your Elasticsearch instance will be restarted and the CORS configuration will be active.
-
-## Step 2: Setup Movies Index
-
-Next we need to setup the index fields, ready for us to ingest data.
-
-The mapping for an index depends on the data you want to index and the features you want.
-
-### Examples
-
-We want to be able to search on title. We need only one field of type text.
-
-```json
-{
- "properties": {
- "title": {
- "type": "text"
- }
- }
-}
-```
-
-We want to be able to search and product facets for writers field. We need two fields of different types: keyword and text.
-
-```json
-{
- "properties": {
- "writers": {
- "type": "text",
- "fields": {
- "keyword": {
- "type": "keyword"
- }
- }
- }
- }
-}
-```
-
-We want to be able to filter on a date field. We only need one date field.
-
-```json
-{
- "properties": {
- "released": {
- "type": "date"
- }
- }
-}
-```
-
-We want to be able to filter on a numeric field. We only need one numeric field. Can be a choice of integer, float and [more documented here](https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html)
-
-```json
-{
- "properties": {
- "imdbRating": {
- "type": "float"
- }
- }
-}
-```
-
-For our movie data-set, we will be using the following fields:
-
-- title (searchable)
-- plot (searchable)
-- genre (searchable, facetable)
-- actors (searchable, facetable)
-- directors (searchable, facetable)
-- released (filterable)
-- imdbRating (filterable)
-- url
-
-The mapping file will be as follows, and we'll once again use Kibana's dev tools console to update the mapping file for our index.
-
-```shell
-PUT /my-example-movies/_mapping
-{
- "properties": {
- "title": {
- "type": "text"
- "fields": {
- "suggest": {
- "type": "search_as_you_type"
- }
- }
- },
- "plot": {
- "type": "text"
- },
- "genre": {
- "type": "text",
- "fields": {
- "keyword": {
- "type": "keyword"
- }
- }
- },
- "actors": {
- "type": "text",
- "fields": {
- "keyword": {
- "type": "keyword"
- }
- }
- },
- "directors": {
- "type": "text",
- "fields": {
- "keyword": {
- "type": "keyword"
- }
- }
- },
- "released": {
- "type": "date"
- },
- "imdbRating": {
- "type": "float"
- },
- "url": {
- "type": "keyword"
- },
- "movie_completion": {
- "type": "completion"
- }
- }
-}
-```
-
-
-
-Elasticsearch will acknowledge the request in the response.
-
-We also want to provide autocomplete functionality, so we need to setup fields for autocomplete.
-
-For suggestions, we want to suggest terms that appear within the actors, directors and genre fields.
-For quick result hits, we want to suggest movies that partially match the title field.
-
-In the above example:
-
-- we have included `movie_completion` field, which is used to provide suggestion completion functionality. This field is not searchable, but is used to provide autocomplete functionality.
-- we have included a `suggest` field for the title field. This field is searchable, but is used to provide "quick hits" functionality.
-
-## Step 3: Index Movies Data
-
-Now with our index and mapping file created, we are ready to index some data! We will use the bulk API to index our data.
-
-We will use the following request. In this example we will be indexing the first movie in the data-set to verify that the data fields is being indexed correctly.
-
-```shell
-PUT /my-example-movies/_bulk
-{ "index": {}}
-{"title": "The Godfather", "released": "1972-03-23T23:00:00.000Z","genre": ["Crime", "Drama"],"directors": ["Francis Ford Coppola"],"actors": ["Marlon Brando", "Al Pacino", "James Caan", "Richard S. Castellano"],"plot": "The aging patriarch of an organized crime dynasty transfers control of his clandestine empire to his reluctant son.","imdbRating": "9.2", "movie_completion": ["Crime", "Drama", "Marlon Brando", "Al Pacino", "James Caan", "Richard S. Castellano"], "url": "https://www.imdb.com/title/tt0068646/"}
-```
-
-## Step 4: Setup CRA for Search UI
-
-First, download the Search-UI's starter app from github by
-
-```shell
-curl https://codeload.github.com/elastic/app-search-reference-ui-react/tar.gz/master | tar -xz
-```
-
-and should appear as a folder called `app-search-reference-ui-react-master`.
-
-Navigate to the root to the folder and install the dependencies using the following command:
-
-```shell
-yarn
-```
-
-### Installing connector
-
-Within the folder, we can now install the `@elastic/search-ui-elasticsearch-connector` library with Yarn.
-
-```shell
-yarn add @elastic/search-ui-elasticsearch-connector
-```
-
-Make sure to check and update Search UI dependencies to the latest version. You can find the latest version by going to [NPM's page for @elastic/search-ui](https://www.npmjs.com/package/@elastic/search-ui).
-
-### Setting up the connector
-
-Open the project within your favorite editor.
-
-Within `src/App.js`, change line 3 to import the Elasticsearch connector. You no longer need the app-search connector.
-
-```js
-import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";
-```
-
-and then update the options to the connector
-
-```js
-const connector = new ElasticsearchAPIConnector({
- host: "",
- apiKey: "",
- index: "my-example-movies"
-});
-```
-
-If you're using Elastic Cloud, you can find your Elasticsearch host within your deployment's details.
-
-
-
-## Step 5: Configure Search UI
-
-Next lets configure Search UI for our needs! Navigate to the config within app.js and update the following:
-
-```js
-const config = {
- searchQuery: {
- search_fields: {
- title: {
- weight: 3
- },
- plot: {},
- genre: {},
- actors: {},
- directors: {}
- },
- result_fields: {
- title: {
- snippet: {}
- },
- plot: {
- snippet: {}
- }
- },
- disjunctiveFacets: ["genre.keyword", "actors.keyword", "directors.keyword"],
- facets: {
- "genre.keyword": { type: "value" },
- "actors.keyword": { type: "value" },
- "directors.keyword": { type: "value" },
- released: {
- type: "range",
- ranges: [
- {
- from: "2012-04-07T14:40:04.821Z",
- name: "Within the last 10 years"
- },
- {
- from: "1962-04-07T14:40:04.821Z",
- to: "2012-04-07T14:40:04.821Z",
- name: "10 - 50 years ago"
- },
- {
- to: "1962-04-07T14:40:04.821Z",
- name: "More than 50 years ago"
- }
- ]
- },
- imdbRating: {
- type: "range",
- ranges: [
- { from: 1, to: 3, name: "Pants" },
- { from: 3, to: 6, name: "Mediocre" },
- { from: 6, to: 8, name: "Pretty Good" },
- { from: 8, to: 10, name: "Excellent" }
- ]
- }
- }
- },
- autocompleteQuery: {
- results: {
- resultsPerPage: 5,
- search_fields: {
- "title.suggest": {
- weight: 3
- }
- },
- result_fields: {
- title: {
- snippet: {
- size: 100,
- fallback: true
- }
- },
- url: {
- raw: {}
- }
- }
- },
- suggestions: {
- types: {
- results: { fields: ["movie_completion"] }
- },
- size: 4
- }
- },
- apiConnector: connector,
- alwaysSearchOnInitialLoad: true
-};
-```
-
-In the above example, we configured the:
-
-- query fields to search on title, plot, genre, actors and directors using the text fields
-- result fields to display title, plot, genre, actors and directors using the text fields
-- facets to display genre, actors and directors using the keyword fields
-- we made the facets disjunctive for better user experience. The user can select more than one facet to expand their search.
-- autocomplete results to suggest results with the same query fields as main search + returning some fields for display.
-
-For more information on configuration, visit the .
-
-### Updating Components
-
-We are going to do several steps here:
-
-- update the `` component to configure autocomplete
-- remove sorting options
-- add a `` component for each facet field
-- update the `` component to display all the fields
-
-```jsx
-
+**Check out the [documentation](https://docs.elastic.co/search-ui) to learn more about setting up and using Search UI.**
+
+## Features 👍
+
+- **You know, for search** - Maintained by [Elastic](https://elastic.co), 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.
+- **Flexible front-end** - Not just for React. Use with any JavaScript library, even vanilla JavaScript.
+- **Flexible back-end** - Use it with Elasticsearch, Elastic Enterprise Search, or any other search API.
+
+## Live demos 👀
+
+### Connectors
+
+- [Elasticsearch](https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox?from-embed=&initialpath=/elasticsearch&file=/src/pages/elasticsearch-basic/index.jsx)
+- [Elastic Site Search (Swiftype)](https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox?from-embed=&initialpath=/site-search&file=/src/pages/site-search/index.jsx)
+
+### Examples
+
+- [Search as you type](https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox?from-embed=&initialpath=/search-as-you-type&file=/src/pages/search-as-you-type/index.jsx)
+- [Search bar in header](https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox?from-embed=&initialpath=/search-bar-in-header&file=/src/pages/search-bar-in-header/index.jsx)
+- [Customizing Styles and Components](https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox?from-embed=&initialpath=/customizing-styles-and-html&file=/src/pages/customizing-styles-and-html/index.jsx)
## Get started
-To quickly get started with Search UI, follow one of our tutorials:
+### Installation
-- [Search UI with Elastic App Search](https://docs.elastic.co/search-ui/tutorials/app-search)
-- [Search UI with Elasticsearch](https://docs.elastic.co/search-ui/tutorials/elasticsearch)
+```
+npm install @elastic/search-ui @elastic/react-search-ui @elastic/react-search-ui-views
+# or
+yarn add @elastic/search-ui @elastic/react-search-ui @elastic/react-search-ui-views
+```
-## Documentation
+### Tutorials
-Check out our [documentation site](https://docs.elastic.co/search-ui) which contains detailed guides for setting up and using Search UI.
+To quickly get started with Search UI, follow one of our tutorials:
+
+- [Search UI with Elasticsearch](https://docs.elastic.co/search-ui/tutorials/elasticsearch)
+- ⚠️ DEPRECATED. [Search UI with Elastic App Search](https://docs.elastic.co/search-ui/tutorials/app-search)
+- ⚠️ DEPRECATED. [Search UI with Elastic Workplace Search](https://docs.elastic.co/search-ui/tutorials/workplace-search)
## Contributing
@@ -21,6 +50,6 @@ We welcome contributors to the project. Follow our [contributing guide](./CONTRI
## License 📗
-[Apache-2.0](https://github.com/elastic/search-ui/blob/master/LICENSE.txt) © [Elastic](https://github.com/elastic)
+[Apache-2.0](https://github.com/elastic/search-ui/blob/main/LICENSE.txt) © [Elastic](https://github.com/elastic)
Thank you to all the [contributors](https://github.com/elastic/search-ui/graphs/contributors)!
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..24c784196
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,17 @@
+# Working with the docs
+
+The [Search UI docs](https://www.elastic.co/guide/en/search-ui/current/overview.html) are written in [Docs V3](https://elastic.github.io/docs-builder/) and are built using [elastic/docs](https://github.com/elastic/docs).
+
+## Build the docs locally
+
+Before building the docs locally make sure you have:
+
+- [docs-builder](https://elastic.github.io/docs-builder/contribute/locally/#step-one) install locally
+
+Install `docs-builder` in a parent directory and run
+
+```
+../docs-builder serve -p ./docs
+```
+
+And open: [http://localhost:3000/reference/](http://localhost:3000/reference/)
diff --git a/docs/api-configuration.mdx b/docs/api-configuration.mdx
deleted file mode 100644
index 559edf699..000000000
--- a/docs/api-configuration.mdx
+++ /dev/null
@@ -1,292 +0,0 @@
----
-id: api-configuration
-slug: /search-ui/api/configuration
-title: Query Configuration
-date: 2022-03-31
-tags: ["configuration"]
----
-
-Below is the configuration of both Search UI query and autocomplete configuration. These configurations are used in conjunction with the API connector to provide data to Search UI.
-
-See 
+