diff --git a/.circleci/config.yml b/.circleci/config.yml
deleted file mode 100644
index 279affddc..000000000
--- a/.circleci/config.yml
+++ /dev/null
@@ -1,36 +0,0 @@
-# Javascript Node CircleCI 2.0 configuration file
-#
-# Check https://circleci.com/docs/2.0/language-javascript/ for more details
-#
-version: 2
-jobs:
- build:
- docker:
- # specify the version you desire here
- - image: circleci/node:10.16
-
- # Specify service dependencies here if necessary
- # CircleCI maintains a library of pre-built images
- # documented at https://circleci.com/docs/2.0/circleci-images/
- # - image: circleci/mongo:3.4.4
-
- working_directory: ~/repo
-
- steps:
- - checkout
-
- # Download and cache dependencies
- - restore_cache:
- keys:
- - v2-dependencies-{{ checksum "package.json" }}
- # fallback to using the latest cache if no exact match is found
- - v2-dependencies-
- - run: npm install
-
- - save_cache:
- paths:
- - node_modules
- key: v2-dependencies-{{ checksum "package.json" }}
-
- # run tests!
- - run: npm run test-ci
diff --git a/.eslintrc.js b/.eslintrc.js
deleted file mode 100644
index 8f7723758..000000000
--- a/.eslintrc.js
+++ /dev/null
@@ -1,32 +0,0 @@
-module.exports = {
- env: {
- node: true,
- browser: true,
- commonjs: true,
- es6: true
- },
- extends: [
- "eslint:recommended",
- "plugin:react/recommended",
- "plugin:jest/recommended",
- "plugin:prettier/recommended",
- "prettier/react"
- ],
- parser: "babel-eslint",
- parserOptions: {
- ecmaFeatures: {
- jsx: true
- },
- ecmaVersion: 2018,
- sourceType: "module"
- },
- plugins: ["react", "jest"],
- settings: {
- react: {
- version: "6.0"
- }
- },
- rules: {
- "no-console": ["error", { allow: ["warn", "error"] }]
- }
-};
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 950015a81..5e300803b 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,10 +1,9 @@
---
name: Bug report
about: Create a report to help us improve
-title: ''
+title: ""
labels: bug
-assignees: ''
-
+assignees: ""
---
**Describe the bug**
@@ -12,6 +11,7 @@ A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
+
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
@@ -24,5 +24,5 @@ A clear and concise description of what you expected to happen.
If applicable, add screenshots to help explain your problem.
**Which backends and packages are you using:**
-Backend: [App Search, Elasticsearch, Site Search, custom]
+Backend: [App Search, Elasticsearch, Site Search, Workplace Search, custom]
Packages: [react-search-ui, search-ui-app-search-connector, etc.]
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 4fe86d5ec..9e3f17ef5 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,10 +1,9 @@
---
name: Feature request
about: Suggest an idea for this project
-title: ''
+title: ""
labels: feature
-assignees: ''
-
+assignees: ""
---
**Is your feature request related to a problem? Please describe.**
diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
index 69dc74acb..ecac281c4 100644
--- a/.github/ISSUE_TEMPLATE/question.md
+++ b/.github/ISSUE_TEMPLATE/question.md
@@ -1,12 +1,11 @@
---
name: Question
about: Questions about using this library
-title: ''
+title: ""
labels: question
-assignees: ''
-
+assignees: ""
---
Please read the following before posting:
-The Enterprise Search team at Elastic maintains this library and are happy to help. Try posting your question to the [Elastic Enterprise Search](https://discuss.elastic.co/c/enterprise-search/84) discuss forums. Be sure to mention that you're using search-ui and also let us know what backend your using; whether it's App Search, Site Search, Elasticsearch, or something else entirely.
+The Enterprise Search team at Elastic maintains this library and are happy to help. Try posting your question to the [Elastic Enterprise Search](https://discuss.elastic.co/c/enterprise-search/84) discuss forums. Be sure to mention that you're using Search UI and also let us know what backend your using; whether it's App Search, Site Search, Workplace Search, Elasticsearch, or something else entirely.
diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml
new file mode 100644
index 000000000..41643049a
--- /dev/null
+++ b/.github/workflows/docs-build.yml
@@ -0,0 +1,13 @@
+name: docs-build
+on:
+ pull_request:
+ types: [opened, synchronize, reopened]
+ push:
+ branches: [main]
+ merge_group: ~
+permissions:
+ contents: read
+ pull-requests: read
+jobs:
+ build:
+ uses: elastic/docs-actions/.github/workflows/docs-build.yml@v1
diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
new file mode 100644
index 000000000..8ee433c2c
--- /dev/null
+++ b/.github/workflows/docs-deploy.yml
@@ -0,0 +1,14 @@
+name: docs-deploy
+on:
+ workflow_run:
+ workflows: [docs-build]
+ types: [completed]
+permissions:
+ contents: read
+ deployments: write
+ id-token: write
+ pull-requests: write
+ actions: read
+jobs:
+ deploy:
+ uses: elastic/docs-actions/.github/workflows/docs-deploy.yml@v1
diff --git a/.github/workflows/docs-preview-cleanup.yml b/.github/workflows/docs-preview-cleanup.yml
new file mode 100644
index 000000000..b234c2358
--- /dev/null
+++ b/.github/workflows/docs-preview-cleanup.yml
@@ -0,0 +1,11 @@
+name: docs-preview-cleanup
+on:
+ pull_request_target:
+ types: [closed]
+permissions:
+ contents: none
+ deployments: write
+ id-token: write
+jobs:
+ cleanup:
+ uses: elastic/docs-actions/.github/workflows/docs-preview-cleanup.yml@v1
diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml
new file mode 100644
index 000000000..f6350d0ca
--- /dev/null
+++ b/.github/workflows/docs-preview.yml
@@ -0,0 +1,23 @@
+name: docs-preview
+on:
+ pull_request_target:
+ types: [opened]
+ paths:
+ - "**.asciidoc"
+ - "**.jpg"
+ - "**.png"
+ - "**.gif"
+
+permissions:
+ pull-requests: write
+
+jobs:
+ doc-preview-pr:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: elastic/docs/.github/actions/docs-preview@master
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ repo: ${{ github.event.repository.name }}
+ preview-path: "guide/index.html"
+ pr: ${{ github.event.pull_request.number }}
diff --git a/.github/workflows/search-ui-ci.yml b/.github/workflows/search-ui-ci.yml
new file mode 100644
index 000000000..3e9232b54
--- /dev/null
+++ b/.github/workflows/search-ui-ci.yml
@@ -0,0 +1,52 @@
+name: Search UI CI
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+ types: [opened, synchronize, reopened]
+ merge_group:
+ types: [checks_requested]
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Use Node.js 20.18.2
+ uses: actions/setup-node@v4
+ with:
+ node-version: 20.18.2
+ cache: "yarn"
+
+ - name: Get yarn cache directory path
+ id: yarn-cache-dir-path
+ run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
+
+ - name: Cache node_modules
+ uses: actions/cache@v3
+ with:
+ path: |
+ node_modules
+ ${{ steps.yarn-cache-dir-path.outputs.dir }}
+ key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+ restore-keys: |
+ ${{ runner.os }}-yarn-
+
+ - name: Install dependencies
+ run: yarn install --frozen-lockfile
+
+ - name: Check formatting
+ run: yarn prettier-check
+
+ - name: Run linter
+ run: yarn lint
+
+ - name: Build project
+ run: yarn build
+
+ - name: Run tests
+ run: yarn test-ci
diff --git a/.gitignore b/.gitignore
index 4ebf070bc..20d3d6ab3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,5 +3,9 @@ lerna-debug.log
storybook-static
.idea
.env
-examples/elasticsearch/netlify-lambda/
package-lock.json
+packages/**/src/version.ts
+packages/**/lib/*
+coverage
+html_docs
+dist
diff --git a/.husky/.gitignore b/.husky/.gitignore
new file mode 100644
index 000000000..31354ec13
--- /dev/null
+++ b/.husky/.gitignore
@@ -0,0 +1 @@
+_
diff --git a/.husky/pre-commit b/.husky/pre-commit
new file mode 100755
index 000000000..c27d8893a
--- /dev/null
+++ b/.husky/pre-commit
@@ -0,0 +1 @@
+lint-staged
diff --git a/.nvmrc b/.nvmrc
index e81c02600..0254b1e63 100644
--- a/.nvmrc
+++ b/.nvmrc
@@ -1 +1 @@
-14.17.0
\ No newline at end of file
+20.18.2
diff --git a/.prettierrc b/.prettierrc
new file mode 100644
index 000000000..36b356317
--- /dev/null
+++ b/.prettierrc
@@ -0,0 +1,3 @@
+{
+ "trailingComma": "none"
+}
diff --git a/.prettierrc.js b/.prettierrc.js
deleted file mode 100644
index 546243f33..000000000
--- a/.prettierrc.js
+++ /dev/null
@@ -1,4 +0,0 @@
-module.exports = {
- trailingComma: 'none',
- singleQuote: false
-};
diff --git a/.vscode/launch.json b/.vscode/launch.json
index f24bb1df3..e49cb04fc 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -1,26 +1,136 @@
{
- // Use IntelliSense to learn about possible attributes.
- // Hover to view descriptions of existing attributes.
- // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
- "version": "0.2.0",
- "configurations": [
- {
- "name": "Jest react-search-ui",
- "type": "node",
- "request": "launch",
- "program": "${workspaceRoot}/packages/react-search-ui/node_modules/jest/bin/jest.js",
- "stopOnEntry": false,
- "args": [
- "--runInBand", "--forceExit", "--detectOpenHandles", "--watch"
- ],
- "cwd": "${workspaceRoot}/packages/react-search-ui",
- "preLaunchTask": null,
- "runtimeExecutable": null,
- "env": {
- "NODE_ENV": "test"
- },
- "console": "integratedTerminal",
- "sourceMaps": true
- }
- ]
+ // Use IntelliSense to learn about possible attributes.
+ // Hover to view descriptions of existing attributes.
+ // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Jest react-search-ui-views",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/react-search-ui-views",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ },
+ {
+ "name": "Jest react-search-ui",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/react-search-ui",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ },
+ {
+ "name": "Jest search-ui",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/search-ui",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ },
+ {
+ "name": "Jest app-search-connector",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/search-ui-app-search-connector",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ },
+ {
+ "name": "Jest elasticsearch-connector",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/search-ui-elasticsearch-connector",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ },
+ {
+ "name": "Jest workplace-connector",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/search-ui-workplace-search-connector",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ },
+ {
+ "name": "Jest analytics-plugin",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/search-ui-analytics-plugin",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ },
+ {
+ "name": "Jest engines-connector",
+ "type": "node",
+ "request": "launch",
+ "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+ "stopOnEntry": false,
+ "args": ["--runInBand", "--forceExit", "--detectOpenHandles", "--watch"],
+ "cwd": "${workspaceRoot}/packages/search-ui-engines-connector",
+ "preLaunchTask": null,
+ "runtimeExecutable": null,
+ "env": {
+ "NODE_ENV": "test"
+ },
+ "console": "integratedTerminal",
+ "sourceMaps": true
+ }
+ ]
}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 000000000..9bf4d12b5
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,4 @@
+{
+ "editor.defaultFormatter": "esbenp.prettier-vscode",
+ "editor.formatOnSave": true
+}
diff --git a/ADVANCED.md b/ADVANCED.md
deleted file mode 100644
index 6b46a0d78..000000000
--- a/ADVANCED.md
+++ /dev/null
@@ -1,1451 +0,0 @@
-# Contents
-
-1. [Headless Core](#headless-core)
-2. [Component Reference](#component-reference)
-3. [Customization](#customization)
-4. [Advanced Configuration](#advanced-configuration)
-5. [Build Your Own Component](#build-your-own-component)
-6. [Connectors and Handlers](#connectors-and-handlers)
-7. [Performance](#performance)
-8. [Debugging](#debugging)
-
-# Headless Core
-
-- [Headless Core Concepts](#headless-core-concepts)
-- [Working with the Headless Core](#working-with-the-headless-core)
-- [Headless Core Reference](#headless-core-reference)
-
-## Headless Core Concepts
-
-```
- |
- @elastic/react-search-ui | @elastic/search-ui
- |
- |
- SearchProvider <--------------- SearchDriver
- | | | |
- State / | | | | State /
- Actions | | | | Actions
- | | | |
- Components | | |
- | | | |
- v v | v
-------------------------------------+----------------------------
- | | |
- v v v
- Using Headless Usage Headless Usage outside
- Components in React of React
-```
-
-The core is a separate, vanilla JS library which can be used for any JavaScript based implementation.
-
-> [@elastic/search-ui](https://github.com/elastic/search-ui/tree/master/packages/search-ui)
-
-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.
-
-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
-
-
- {/*WithSearch exposes the "Context"*/}
- {context => {
- // Context contains state, like "searchTerm"
- const searchTerm = context.searchTerm;
- // Context also contains actions, like "setSearchTerm"
- const setSearchTerm = context.setSearchTerm;
- return (
-
- {/*An out-of-the-box Component like SearchBox uses State and Actions under the hood*/}
-
- {/*We could work directly with those State and Actions also */}
-
-
- );
- }}
-
-
-```
-
-## Working with the Headless Core
-
-If you wish to work with Search UI outside of a particular Component, you'll work
-directly with the core.
-
-There are two methods for accessing the headless core directly, `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.
-
-Both methods expose a `mapContextToProps` function which allows you to pick which state and actions
-from context you need to work with.
-
-### 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 |
-| ------- | ------ | ------------------- |
-| context | Object | The current Context |
-| props | Object | The current props |
-
-ex.:
-
-```jsx
-// Selects `searchTerm` and `setSearchTerm` for use in Component
-withSearch(({ searchTerm, setSearchTerm }) => ({
- searchTerm,
- setSearchTerm
-}))(Component);
-
-// Uses current `props` to conditionally modify context
-withSearch(({ searchTerm }, { someProp }) => ({
- searchTerm: someProp ? "" : searchTerm
-}))(Component);
-```
-
-### withSearch
-
-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).
-
-### WithSearch
-
-This is the [Render Props](https://reactjs.org/docs/render-props.html) approach to working with the core.
-
-One use case for that would be to render a "loading" indicator any time the application is fetching data.
-
-For example:
-
-```jsx
-
- ({ isLoading })}>
- {({ isLoading }) => (
-
- )}
-
-
-```
-
-### Combining Actions
-
-There are certain cases where you may need to apply one or more actions at a time. Search UI intelligently
-batches actions into a single API call.
-
-For example, if you need to apply two filters at once, it is perfectly acceptable to write the following code:
-
-```
-addFilter("states", "Alaska", "any");
-addFilter("world_heritage_site", "true");
-```
-
-This will only result in a single API call.
-
-## Headless Core Reference
-
-### SearchProvider
-
-The `SearchProvider` is a top-level Component which is essentially a wrapper around the core.
-
-It exposes the [State](#state) and [Actions](#actions) of the core in a [Context](#context).
-
-Params:
-
-| name | type | description |
-| -------- | ---------- | ------------------------------------------------------------------ |
-| config | Object | See the [Advanced Configuration](#advanced-configuration) section. |
-| children | React Node | |
-
-### Context
-
-The "Context" is a flattened object containing, as keys, all [State](#state) and [Actions](#actions).
-
-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
- ...
-}
-```
-
-### Actions
-
-| method | params | return | description |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `addFilter` | `name` String - field name to filter on `value` [FilterValue](./packages/react-search-ui/src/types/FilterValue.js) to apply `filterType` String - type of filter to apply: "all", "any", or "none" | | Add a filter in addition to current filters values. |
-| `setFilter` | `name` String - field name to filter on `value` [FilterValue](./packages/react-search-ui/src/types/FilterValue.js) to apply `filterType` String - type of filter to apply: "all", "any", or "none" | | Set a filter value, replacing current filter values. |
-| `removeFilter` | `name` String - field to remove filters from `value` String - (Optional) Specify which filter value to remove `filterType` String - (Optional) Specify which filter type to remove: "all", "any", or "none" | | Removes filters or filter values. |
-| `reset` | | | Reset state to initial search state. |
-| `clearFilters` | `except` Array[String] - List of field names that should NOT be cleared | | Clear all filters. |
-| `setCurrent` | Integer | | Update the current page number. Used for paging. |
-| `setResultsPerPage` | Integer | | |
-| `setSearchTerm` | `searchTerm` String `options` Object `options.refresh` Boolean - Refresh search results on update. Default: `true`. `options.debounce` Number - Length to debounce any resulting queries. `options.shouldClearFilters` Boolean - Should existing filters be cleared? Default: `true`. `options.autocompleteSuggestions` Boolean - Fetch query suggestions for autocomplete on update, stored in `autocompletedSuggestions` state `options.autocompleteResults` Boolean - Fetch results on update, stored in `autocompletedResults` state | | |
-| `setSort` | `sort \| sortField` One of: [SortList](./packages/react-search-ui/src/types/SortList.js) \| String - field to sort on `sortDirection` String - "asc" or "desc" | | |
-| `trackClickThrough` | `documentId` String - The document ID associated with the result that was clicked `tag` - Array[String] Optional tags which can be used to categorize this click event | | Report a clickthrough event, which is when a user clicks on a result link. |
-| `a11yNotify` | `messageFunc` String - object key to run as function `messageArgs` Object - Arguments to pass to form your screen reader message string | | Reads out a screen reader accessible notification. See `a11yNotificationMessages` under [Advanced Configuration](#advanced-configuration) |
-
-### State
-
-State can be divided up into a few different types.
-
-1. Request State - State that is used as parameters on Search API calls.
-2. Result State - State that represents a response from a Search API call.
-3. Application State - The general state.
-
-Request State and Result State will often have similar values. For instance, `searchTerm` and `resultSearchTerm`.
-`searchTerm` is the current search term in the UI, and `resultSearchTerm` is the term associated with the current
-`results`. This can be relevant in the UI, where you might not want the search term on the page to change until AFTER
-a response is received, so you'd use the `resultSearchTerm` state.
-
-#### Request State
-
-State that is used as parameters on Search API calls.
-
-Request state can be set by:
-
-- Using actions, like `setSearchTerm`
-- The `initialState` option.
-- The URL query string, if `trackUrlState` is enabled.
-
-| option | type | required? | source |
-| -------------------------------------------------- | ------------------------------------------------------------------- | --------- | ------------------------------------------ |
-| `current` | Integer | optional | Current page number |
-| `filters` | Array[[Filter](./packages/react-search-ui/src/types/Filter.js)] | optional | |
-| `resultsPerPage` | Integer | optional | Number of results to show on each page |
-| `searchTerm` | String | optional | Search terms to search for |
-| `sort` | [SortList](./packages/react-search-ui/src/types/SortList.js) | optional | List of fields and directions to sort on |
-| `sortDirection` **deprecated, use `sort` instead** | String ["asc" \| "desc"] | optional | Direction to sort |
-| `sortField` **deprecated, use `sort` instead** | String | optional | Name of field to sort on |
-
-#### Response State
-
-State that represents a response from a Search API call.
-
-It is not directly update-able.
-
-It is updated indirectly by invoking an action which results in a new API request.
-
-| field | type | description |
-| ----------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `autocompletedResults` | Array[[Result](./packages/react-search-ui/src/types/Result.js)] | An array of results items fetched for an autocomplete dropdown. |
-| `autocompletedResultsRequestId` | String | A unique ID for the current autocompleted search results. |
-| `autocompletedSuggestions` | Object[String, Array[[Suggestion](./packages/react-search-ui/src/types/Suggestion.js)] | A keyed object of query suggestions. It's keyed by type since multiple types of query suggestions can be set here. |
-| `autocompletedSuggestionsRequestId` | String | A unique ID for the current autocompleted suggestion results. |
-| `facets` | Object[[Facet](./packages/react-search-ui/src/types/Facet.js)] | Will be populated if `facets` configured in [Advanced Configuration](#advanced-configuration). |
-| `rawResponse` | Object | The response object received from the API |
-| `requestId` | String | A unique ID for the current search results. |
-| `results` | Array[[Result](./packages/react-search-ui/src/types/Result.js)] | An array of result items. |
-| `resultSearchTerm` | String | As opposed the the `searchTerm` state, which is tied to the current search parameter, this is tied to the searchTerm for the current results. There will be a period of time in between when a request is started and finishes where the two pieces of state will differ. |
-| `totalResults` | Integer | Total number of results found for the current query. |
-
-#### Application State
-
-Application state is the general application state.
-
-| field | type | description |
-| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
-| `error` | String | Error message, if an error was thrown. |
-| `isLoading` | boolean | Whether or not a search is currently being performed. |
-| `wasSearched` | boolean | Has any query been performed since this driver was created? Can be useful for displaying initial states in the UI. |
-
-# Component Reference
-
-Note that all components in this library are Pure Components. Read more
-about that [here](#performance).
-
-The following Components are available:
-
-- [SearchBox](#searchbox)
-- [Results](#results)
-- [Result](#result)
-- [ResultsPerPage](#resultsperpage)
-- [Facet](#facet)
-- [Sorting](#sorting)
-- [Paging](#paging)
-- [PagingInfo](#paginginfo)
-- [ErrorBoundary](#errorboundary)
-
-## SearchBox
-
-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
-[Advanced Configuration](#advanced-configuration) 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 [Advanced Configuration Guide](#advanced-configuration) 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
-does 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 | type | Required? | Default | Options | Description |
-| ----------------------------- | ---------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| className | String | no | | | |
-| shouldClearFilters | Boolean | no | true | | Should existing filters be cleared when a new search is performed? |
-| inputProps | Object | no | | | Props for underlying 'input' element. I.e., `{ placeholder: "Enter Text"}`. |
-| searchAsYouType | Boolean | no | false | | Executes a new search query with every key stroke. You can fine tune the number of queries made by adjusting the `debounceLength` parameter. |
-| debounceLength | Number | no | 200 | | 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 | Render Function | no | [SearchBox](packages/react-search-ui-views/src/SearchBox.js) | | Used to override the default view for this Component. See the [Customization: Component views and HTML](#component-views-and-html) section for more information. |
-| autocompleteResults | Boolean or [AutocompleteResultsOptions](#AutocompleteResultsOptions) | Object | no | | Configure and autocomplete search results. Boolean option is primarily available for implementing custom views. |
-| autocompleteSuggestions | Boolean or [AutocompleteSuggestionsOptions](#AutocompleteSuggestionsOptions) | Object | no | | 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 | Integer | no | 0 | | Minimum number of characters before autocompleting. |
-| autocompleteView | Render Function | no | [Autocomplete](packages/react-search-ui-views/src/Autocomplete.js) | | Provide a different view just for the autocomplete dropdown. |
-| inputView | Render Function | no | [SearchInput](packages/react-search-ui-views/src/SearchInput.js) | | Provide a different view just for the input section. |
-| onSelectAutocomplete | Function(selection. options, defaultOnSelectAutocomplete) | no | | | 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 | Function(searchTerm) | no | | | Allows overriding behavior when submitted. Receives the search term from the search box. |
-
-#### AutocompleteResultsOptions
-
-| Name | type | Required? | Default | Options | Description |
-| ----------------------- | ------------- | --------- | ------- | ------- | --------------------------------------------------------- |
-| linkTarget | String | no | \_self | | Used to open links in a new tab. |
-| sectionTitle | String | no | | | Title to show in section within dropdown. |
-| shouldTrackClickThrough | Boolean | no | true | | Only applies to Results, not Suggestions. |
-| clickThroughTags | Array[String] | no | | | Tags to send to analytics API when tracking clickthrough. |
-| titleField | String | yes | | | Field within a Result to use as the "title". |
-| urlField | String | yes | | | Field within a Result to use for linking. |
-
-#### AutocompleteSuggestionsOptions
-
-| Name | type | Required? | Default | Options | Description |
-| ------------ | ------ | --------- | ------- | ------- | ---------------------------------------- |
-| sectionTitle | String | no | | | Title to show in section within dropdown |
-
----
-
-## Results
-
-Displays all search results.
-
-### Example
-
-```jsx
-
-import { Results } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### 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 [Advanced Configuration](#advanced-configuration) guide
-for more information.
-
-### Properties
-
-| Name | type | Required? | Default | Options | Description |
-| ----------------------- | --------------- | --------- | -------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| resultView | Render Function | no | [Result](packages/react-search-ui-views/src/Result.js) | | Used to override individual Result views. See the Customizing Component views and html section for more information. |
-| titleField | String | no | | | Name of field to use as the title from each result. |
-| shouldTrackClickThrough | Boolean | no | true | | Whether or not to track a clickthrough event when clicked. |
-| clickThroughTags | Array[String] | no | | | Tags to send to analytics API when tracking clickthrough. |
-| urlField | String | no | | | Name of field to use as the href from each result. |
-| thumbnailField | String | no | | | Name of field to use for thumbnail image. Should be a valid URL and at least 220px wide. |
-| view | Render Function | no | [Results](packages/react-search-ui-views/src/Results.js) | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-
----
-
-## 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 [Advanced Configuration](#advanced-configuration) guide
-for more information.
-
-### Properties
-
-| Name | type | Required? | Default | Options | Description |
-| ----------------------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| titleField | String | no | | | Name of field to use as the title from each result. |
-| shouldTrackClickThrough | Boolean | no | true | | Whether or not to track a clickthrough event when clicked. |
-| clickThroughTags | Array[String] | no | | | Tags to send to analytics API when tracking clickthrough. |
-| urlField | String | no | | | Name of field to use as the href from each result. |
-| view | Render Function | no | [Result](packages/react-search-ui-views/src/Result.js) | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-| result | [Result](packages/react-search-ui-views/src/types/Result.js) | no | | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-
----
-
-## ResultsPerPage
-
-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 [`resultsPerPage`](#resultsPerPageProp) value, which is 20 by default.
-To override `resultsPerPage` default value [refer to the custom options example](#Example-using-custom-options).
-
-### Example
-
-```jsx
-
-import { ResultsPerPage } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Example using custom options
-
-```jsx
-
-import { SearchProvider, ResultsPerPage } from "@elastic/react-search-ui";
-
-
-
-
-```
-
-### Properties
-
-| Name | type | Required? | Default | Options | Description |
-| --------- | --------------- | --------- | ---------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| options | Array[Number] | no | [20, 40, 60] | | Dropdown options to select the number of results to show per page. |
-| view | Render Function | no | [ResultsPerPage](packages/react-search-ui-views/src/ResultsPerPage.js) | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-
----
-
-## Facet
-
-Show a Facet filter for a particular field.
-
-Must configure the corresponding field in the `SearchProvider` [facets](#advanced-configuration) 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 | type | Required? | Default | Options | Description |
-| ------------ | --------------- | --------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| field | String | yes | | | Field name corresponding to this filter. This requires that the corresponding field has been configured in `facets` on the top level Provider. |
-| filterType | String | no | "all" | "all", "any", "none" | 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 | String | yes | | | A static label to show in the facet filter. |
-| show | Number | no | 5 | | The number of facet filter options to show before concatenating with a "more" link. |
-| view | Render Function | no | [MultiCheckboxFacet](packages/react-search-ui-views/src/MultiCheckboxFacet.js) | [SingleLinksFacet](packages/react-search-ui-views/src/SingleLinksFacet.js) [SingleSelectFacet](packages/react-search-ui-views/src/SingleSelectFacet.js) [BooleanFacet](packages/react-search-ui-views/src/BooleanFacet.js) | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-| isFilterable | Boolean | no | false | | Whether or not to show Facet quick filter. |
-
----
-
-## Sorting
-
-Shows a dropdown for selecting the current Sort.
-
-### Example
-
-```jsx
-
-import { Sorting } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Properties
-
-| Name | type | Required? | Default | Options | Description |
-| ----------- | --------------------------------------------------------------------- | --------- | -------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| label | Array[[SortOption](packages/react-search-ui/src/types/SortOption.js)] | no | | | A static label to show in the Sorting Component. |
-| sortOptions | Array[[SortOption](packages/react-search-ui/src/types/SortOption.js)] | yes | | | |
-| view | Render Function | no | [Sorting](packages/react-search-ui-views/src/Sorting.js) | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-
----
-
-## Paging
-
-Navigate through pagination.
-
-### Example
-
-```jsx
-
-import { Paging } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Properties
-
-| Name | type | Required? | Default | Options | Description |
-| --------- | --------------- | --------- | ------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| view | Render Function | no | [Paging](packages/react-search-ui-views/src/Paging.js) | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-
----
-
-## PagingInfo
-
-Paging details, like "1 - 20 of 100 results".
-
-### Example
-
-```jsx
-
-import { PagingInfo } from "@elastic/react-search-ui";
-
-...
-
-
-```
-
-### Properties
-
-| Name | type | Required? | Default | Options | Description |
-| --------- | --------------- | --------- | -------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| view | Render Function | no | [PagingInfo](packages/react-search-ui-views/src/PagingInfo.js) | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-
----
-
-## ErrorBoundary
-
-Handle unexpected errors.
-
-### Example
-
-```jsx
-import { ErrorBoundary } from "@elastic/react-search-ui";
-
-...
-
-
-
Some Content
-
-```
-
-### Properties
-
-| Name | type | Required? | Default | Options | Description |
-| --------- | --------------- | --------- | -------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | String | no | | | |
-| children | React node | yes | | | Content to show if no error has occurred, will be replaced with error messaging if there was an error. |
-| view | Render Function | no | [ErrorBoundary](packages/react-search-ui-views/src/ErrorBoundary.js) | | Used to override the default view for this Component. See [Customization: Component views and HTML](#component-views-and-html) for more information. |
-
-# Customization
-
-- [Custom Styles and Layout](#custom-styles-and-layout)
-- [Component Views and HTML](#component-views-and-html)
-- [Component Behavior](#component-behavior)
-
-## Custom Styles and Layout
-
-Styling is up to you.
-
-You can choose use the out of the box styles, or customize them.
-
-To provide custom styles:
-
-1. Write your own styles that target the class names in the individual Components. Do **NOT** include `styles.css`.
-2. Override the default styles. Include `styles.css`, and then overwrite with your own styles.
-
-For layout, provide your own layout instead of using the `Layout` Component.
-
-For views and HTML, see the next section.
-
-## Component Views and HTML
-
-All Components in this library can be customized by providing a `view` prop.
-
-Each Component's `view` will have a custom signature.
-
-This follows the [React Render Props](https://reactjs.org/docs/render-props.html) pattern.
-
-The clearest way to determine a Component's `view` function signature is to
-look at the corresponding view Component's source code in
-[react-search-ui-views](packages/react-search-ui-views/). Each Component in that
-library implements a `view` function for a Component in the React library, so it
-serves as a great reference.
-
-For example, if we were to customize the `PagingInfo` Component...
-
-We'd look up the default view from the [Components Reference](#component-reference) section for the `PagingInfo` Component.
-
-The corresponding view is [PagingInfo](packages/react-search-ui-views/src/PagingInfo.js) -- see how the naming matches up?
-
-After viewing that Component's source, you'll see it accepts 4 props:
-
-1. `end`
-2. `searchTerm`
-3. `start`
-4. `totalResults`
-
-In our case, we care about the `start` and `end` values.
-
-We provide a view function that uses those two props:
-
-```jsx
- (
-
-
- {start} - {end}
-
-
- )}
-/>
-```
-
-We could also accomplish this with a functional Component:
-
-```jsx
-const PagingInfoView = ({ start, end }) => (
-
-
- {start} - {end}
-
-
-);
-
-return ;
-```
-
-## Component Behavior
-
-**It will be helpful to read the [Headless Core](#headless-core) section first.**
-
-We have two primary recommendations for customizing Component behavior:
-
-1. Override state and action props before they are passed to your Component, using the `mapContextToProps` param. This
- will override the default [mapContextToProps](#mapContextToProps) for the component.
-2. Override props before they are passed to your Component's view.
-
-### Override mapContextToProps
-
-Every Component supports a `mapContextToProps` prop, which allows you to modify state and actions
-before they are received by the Component.
-
-**NOTE** This MUST be an immutable function. If you directly update the props or context, you will have major issues in your application.
-
-A practical example might be putting a custom sort on your facet data.
-
-This example orders a list of states by name:
-
-```jsx
- {
- if (!context.facets.states) return context;
- return {
- ...context,
- facets: {
- ...(context.facets || {}),
- states: context.facets.states.map(s => ({
- ...s,
- data: s.data.sort((a, b) => {
- if (a.value > b.value) return 1;
- if (a.value < b.value) return -1;
- return 0;
- })
- }))
- }
- };
- }}
- field="states"
- label="States"
- show={10}
-/>
-```
-
-### Overriding view props
-
-An example of this is modifying the `onChange` handler of the `Paging` Component
-view. Hypothetically, you may need to know every time a user
-pages past page 1, indicating that they are not finding what they need on the first page
-of search results.
-
-```jsx
-import { Paging } from "@elastic/react-search-ui";
-import { Paging as PagingView } from "@elastic/react-search-ui-views";
-
-function reportChange(value) {
- // Some logic to report the change
-}
-
-
- PagingView({
- ...props,
- onChange: value => {
- reportChange(value);
- return props.onChange(value);
- }
- })
- }
-/>;
-```
-
-In this example, we did the following:
-
-1. Looked up what the default view is for our Component in the
- [Component Reference](#component-reference) guide.
-2. Imported that view as `PagingView`.
-3. Passed an explicit `view` to our `Paging` Component, overriding
- the `onChange` prop with our own implementation, and ultimately rendering
- `PagingView` with the updated props.
-
-# Advanced Configuration
-
-All configuration for Search UI is provided in a single configuration object.
-
-```jsx
-const configurationOptions = {
- apiConnector: connector,
- searchQuery: {
- disjunctiveFacets: ["acres"],
- disjunctiveFacetsAnalyticsTags: ["Ignore"],
- search_fields: {
- title: {},
- description: {}
- },
- result_fields: {
- title: {
- snippet: {
- size: 100,
- fallback: true
- }
- },
- nps_link: {
- raw: {}
- },
- description: {
- snippet: {
- size: 100,
- fallback: true
- }
- }
- },
- facets: {
- states: { type: "value", size: 30 },
- acres: {
- type: "range",
- ranges: [
- { from: -1, name: "Any" },
- { from: 0, to: 1000, name: "Small" },
- { from: 1001, to: 100000, name: "Medium" },
- { from: 100001, name: "Large" }
- ]
- }
- }
- },
- hasA11yNotifications: true,
- a11yNotificationMessages: {
- searchResults: ({ start, end, totalResults, searchTerm }) =>
- `Searching for "${searchTerm}". Showing ${start} to ${end} results out of ${totalResults}.`
- },
- alwaysSearchOnInitialLoad: true
-};
-
-return (
-
- {() => (
-
- }
- bodyContent={}
- />
-
- )}
-
-);
-```
-
-**It is helpful to [read the section on the headless core](#headless-core) first!**
-
-| option | type | required? | default | description |
-| --------------------------- | ----------------------------------------------------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `apiConnector` | APIConnector | optional | | Instance of a Connector. For instance, [search-ui-app-search-connector](packages/search-ui-app-search-connector). |
-| `onSearch` | function | optional | | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Connectors and Handlers](#connectors-and-handlers) for more information. |
-| `onAutocomplete` | function | optional | | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Connectors and Handlers](#connectors-and-handlers) for more information. |
-| `onResultClick` | function | optional | | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Connectors and Handlers](#connectors-and-handlers) for more information. |
-| `onAutocompleteResultClick` | function | optional | | You may provide individual handlers instead of a Connector, override individual Connector handlers, or act as middleware to Connector methods. See [Connectors and Handlers](#connectors-and-handlers) for more information. |
-| `autocompleteQuery` | Object | optional | {} | Configuration options for the main search query. |
-| | - `results` - [Query Config](#query-config) | | | Configuration options for results query, used by autocomplete. |
-| | - `suggestions` - [Suggestions Query Config](#suggestions-query-config) | | | Configuration options for suggestions query, used by autocomplete. |
-| `debug` | Boolean | optional | false | Trace log actions and state changes. |
-| `initialState` | Object | optional | | Set initial [State](#state) of the search. Any [Request State](#request-state) can be set here. This is useful for defaulting a search term, sort, etc.
Example: `{ searchTerm: "test", resultsPerPage: 40 }` |
-| `searchQuery` | [Query Config](#query-config) | optional | {} | Configuration options for the main search query. |
-| `trackUrlState` | Boolean | optional | true | By default, [Request State](#request-state) will be synced with the browser url. To turn this off, pass `false`. |
-| `urlPushDebounceLength` | Integer | optional | 500 | 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. |
-| `hasA11yNotifications` | Boolean | optional | false | 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. |
-| `a11yNotificationMessages` | Object | optional | {} | 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 | optional | false | If true, Search UI will always do an initial search, even when no inital Request State is set. |
-
-## Query Config
-
-Query configuration for Search UI largely follows the same API as the [App Search Search API](https://swiftype.com/documentation/app-search/api/search).
-
-For example, if you add a `search_fields` configuration option, it will control which fields are actually returned from the API.
-
-| option | type | required? | default | description |
-| ---------------------------------- | ------------------------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `facets` | Object | optional | | [App Search Facets API Reference](https://swiftype.com/documentation/app-search/api/search/facets). Tells Search UI to fetch facet data that can be used to build [Facet](#facet) Components.
Example, using `states` field for faceting: `facets: {states: { type: "value", size: 30 }` |
-| `disjunctiveFacets` | Array[String] | optional | | An array of field names. Every field listed here must have been configured in the `facets` field first. It denotes that a facet should be considered disjunctive. When returning counts for disjunctive facets, the counts will be returned as if no filter is applied on this field, even if one is applied.
Example, specifying `states` field as disjunctive: `disjunctiveFacets: ['states']` |
-| `disjunctiveFacetsAnalyticsTags` | Array[String] | optional | | Used in conjunction with the `disjunctiveFacets` parameter. Adding `disjunctiveFacets` can cause additional API requests to be made to your API, which can create deceiving analytics. These queries will be tagged with "Facet-Only" by default. This field lets you specify a different tag for these.
Example, use `junk` as a tag on all disjunctive API calls: `disjunctiveFacetsAnalyticsTags: ['junk']` |
-| `conditionalFacets` | Object[String, function] | optional | | This facet will only be fetched if the condition specified returns `true`, based on the currently applied filters. This is useful for creating hierarchical facets.
Example: don't return `states` facet data unless `parks` is a selected filter. `{ states: filters => isParkSelected(filters) }` |
-| `search_fields` | Object[String, Object] | optional | | Fields which should be searched with search term.
[App Search search_fields API Reference](https://swiftype.com/documentation/app-search/api/search/search-fields) |
-| `result_fields` | Object[String, Object] | optional | | Fields which should be returned in results.
[App Search result_fields API Reference](https://swiftype.com/documentation/app-search/api/search/result-fields) |
-| \* [Request State](#request-state) | | optional | | Any request state value can be provided here. If provided, it will ALWAYS override the value from state. |
-
-## Global filters
-
-Using Query Config, it is possible to create "Global" filters. "Global filters" are filters that are added to _every_ query. The user has no control over whether or not this filter is added or removed, it doesn't show up in the query string, and is completely transparent to the user. It is applied IN ADDITION to filters which the user applies.
-
-```jsx
-
-
-```
-
-## Suggestions Query Config
-
-Suggestions Query configuration for Search UI largely follows the same API as the [App Search Search API](https://swiftype.com/documentation/app-search/api/query-suggestion).
-
-Ex.
-
-```json
-{
- "types": {
- "documents": {
- "fields": ["title", "states"]
- }
- },
- "size": 4
-}
-```
-
-| option | type | required? | source |
-| ------- | ------- | --------- | -------------------------------------------------------------------------------------------- |
-| `types` | Object | required | Object, keyed by "type" of query suggestion, with configuration for that type of suggestion. |
-| `size` | Integer | optional | Number of suggestions to return. |
-
-## API Config
-
-Search UI makes all of the search API calls for your application.
-
-You can control what these API calls look like with options such as `search_fields`, `result_fields`, and `facets`.
-
-But there may be cases where certain API operations are not supported by Search UI.
-
-For example, [App Search](https://www.elastic.co/cloud/app-search-service) supports a "grouping" feature, which Search UI does not support out of the box.
-
-We can work around that by using the `beforeSearchCall` hook on the App Search Connector. This acts as a middleware
-that gives you an opportunity to modify API requests and responses before they are made.
-
-```js
-const connector = new AppSearchAPIConnector({
- searchKey: "search-371auk61r2bwqtdzocdgutmg",
- engineName: "search-ui-examples",
- hostIdentifier: "host-2376rb",
- beforeSearchCall: (existingSearchOptions, next) =>
- next({
- ...existingSearchOptions,
- group: { field: "title" }
- })
-});
-```
-
-# Build Your Own Component
-
-**Learn about the [Headless Core](#headless-core) concepts first!**
-
----
-
-We provide a variety of Components out of the box.
-
-There might be cases where we do not have the Component you need.
-
-In this case, we provide a [Higher Order Component](https://reactjs.org/docs/higher-order-components.html)
-called [withSearch](./packages/react-search-ui/src/withSearch.js).
-
-It gives you access to work directly with Search UI's [Headless Core](#headless-core).
-
-This lets you create your own Components for Search UI.
-
-Ex. Creating a Component for clearing all filters
-
-```jsx
-import React from "react";
-import { withSearch } from "@elastic/react-search-ui";
-
-function ClearFilters({ filters, clearFilters }) {
- return (
-
-
-
- );
-}
-
-export default withSearch(({ filters, clearFilters }) => ({
- filters,
- clearFilters
-}))(ClearFilters);
-```
-
-Note that `withSearch` accepts a `mapContextToProps` function as the first parameter. Read more about that
-in the [mapContextToProps](#mapContextToProps) section.
-
-Also note that all components created with `withSearch` will be Pure Components. Read more
-about that [here](#performance).
-
-# Connectors and Handlers
-
-**Learn about the [Headless Core](#headless-core) concepts first!**
-
----
-
-Search UI exposes a number of event hooks which need handlers to be implemented in order for Search UI
-to function properly.
-
-The easiest way to provide handlers for these events is via an out-of-the-box "Connector", which
-provides pre-built handlers, which can then be configured for your particular use case.
-
-While we do provide out-of-the-box Connectors, it is also possible to implement these handlers directly,
-override Connector methods, or provide "middleware" to Connectors in order to further customize
-how Search UI interacts with your services.
-
-#### Event Handlers
-
-| method | params | return | description |
-| --------------------------- | ----------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `onResultClick` | `props` - Object | | This method logs a click-through event to your APIs analytics service. This is triggered when a user clicks on a result on a result page. |
-| | - `query` - String | | The query used to generate the current results. |
-| | - `documentId` - String | | The id of the result that a user clicked. |
-| | - `requestId` - String | | A unique id that ties the click to a particular search request. |
-| | - `tags` - Array[String] | | Tags used for analytics. |
-| `onSearch` | `state` - [Request State](#request-state) | [Response State](#response-state) | |
-| | `queryConfig` - [Query Config](#query-config) | | |
-| `onAutocompleteResultClick` | `props` - Object | | This method logs a click-through event to your APIs analytics service. This is triggered when a user clicks on a result in an autocomplete dropdown |
-| | - `query` - String | | The query used to generate the current results. |
-| | - `documentId` - String | | The id of the result that a user clicked. |
-| | - `requestId` - String | | A unique id that ties the click to a particular search request. |
-| | - `tags` - Array[String] | | Tags used for analytics. |
-| `onAutocomplete` | `state` - [Request State](#request-state) | [Response State](#response-state) | |
-| | `queryConfig` - Object | | |
-| | - `results` - [Query Config](#query-config) | | If this is set, results should be returned for autocomplete. |
-| | - `suggestions` - [Suggestions Query Config](#suggestions-query-config) | | If this is set, query suggestions should be returned for autocomplete. |
-
-### Implementing Handlers without a Connector
-
-If you are using an API for search that there is no Connector for, it is possible to simply provide
-handler implementations directly on the `SearchProvider`.
-
-```jsx
- {
- const queryForOtherService = transformSearchUIStateToQuery(state);
- const otherServiceResponse = await callSomeOtherService(
- queryForOtherService
- );
- return transformOtherServiceResponseToSearchUIState(otherServiceResponse);
- }
- }}
-/>
-```
-
-This makes Search UI useful for services like `elasticsearch` which do not have a Connector
-available.
-
-For a thorough example of this, see the demo in [examples/elasticsearch](examples/elasticsearch/README.md)
-
-### Overriding Connector Handlers
-
-Explicitly providing a Handler will override the Handler provided by the Connector.
-
-```jsx
- {
- const queryForOtherService = transformSearchUIStateToQuery(
- state,
- queryConfig
- );
- const otherServiceResponse = await callSomeOtherService(
- queryForOtherService
- );
- return transformOtherServiceResponseToSearchUIState(otherServiceResponse);
- }
- }}
-/>
-```
-
-### Using middleware in Connector Handlers
-
-Handler implementations can also be used as middleware for Connectors by leveraging
-the `next` function.
-
-```jsx
- {
- const updatedState = someStateTransformation(state);
- return next(updatedState, queryConfig);
- }
- }}
-/>
-```
-
-### Build your own Connector
-
-An example of a connector is the [Site Search API Connector](./packages/search-ui-site-search-connector/README.md).
-
-A connector simply needs to implement the Event Handlers listed above. The handlers typically:
-
-1. Convert the current [Request State](#request-state) and [Query Config](#query-config) into the search semantics of
- your particular Search API.
-2. Convert the response from your particular Search API into [Response State](#response-state).
-
-While some handlers are meant for fetching data and performing searches, other handlers are meant for recording
-certain user events in analytics services, such as `onResultClick` or `onAutocompleteResultClick`.
-
-#### Errors
-
-For error handling, a method must throw any error with a "message" field populated for any unrecoverable error. This
-includes things like 404s, 500s, etc.
-
-# Performance
-
-This library is optimized to avoid full sub-tree re-rendering, and so that components only re-render when state changes
-that are relevant to those particular components occur.
-
-In order to accomplish this, all components within
-this library are "Pure Components". You can read more about the concept and potential pitfalls
-of Pure Components in the React
-[Optimizing Performance](https://reactjs.org/docs/optimizing-performance.html#avoid-reconciliation) guide.
-
-The thing to be most cautious of is not to
-[mutate state](https://reactjs.org/docs/optimizing-performance.html#the-power-of-not-mutating-data) that you will
-pass as props to any of these components.
-
-Example of what not to do:
-
-```jsx
-class SomeComponent extends React.Component {
- changeSorting = () => {
- const { options } = this.state;
- // Mutating an existing array in state rather than creating a new one is bad. Since Sorting component is "Pure"
- // it won't update after calling `setState` here.
- options.push("newOption");
- this.setState({ options });
- };
-
- render() {
- const { options } = this.state;
- return ;
- }
-}
-```
-
-Instead, do:
-
-```jsx
-// Create a new options array and copy the old values into that new array.
-this.setState(prevState => ({ options: [...prevState.options, "newOption"] }));
-```
-
-If you ever need to debug performance related issues, see the instructions in the Optimizing Performance guide for
-enabling the "Highlight Updates" feature in the
-[React Developer tools for Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi).
-
-# Debugging
-
-There is a `debug` flag available on the configuration for `SearchDriver` and `SearchProvider`.
-
-```jsx
-
-```
-
-Setting this to `true` will make the `searchUI` object available globally on window. This will allow you to
-programmatically execute actions in the browser console which can be helpful for debugging.
-
-```js
-window.searchUI.addFilter("states", "California", "all");
-```
-
-This will also log actions and state updates as they occur to the console in the following form:
-
-```
-Search UI: Action {Action Name} {Action Parameters}
-Search UI: State Update {State to update} {Full State after update}
-```
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 000000000..328fabe0b
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.24.0] - 2025-05-28
+
+### ✨ Added
+
+- Replaced Searchkit SDK with a new internal `ApiClient` architecture for the Elasticsearch Connector. This significantly improves maintainability, customizability, and bundle size. [#1143](https://github.com/elastic/search-ui/pull/1143)
+- Added support for filters in Autocomplete results. [#1150](https://github.com/elastic/search-ui/pull/1150)
+- Introduced new advanced query customization options via `getQueryFn` and `interceptSearchRequest`, `interceptAutocompleteResultsRequest`, `interceptAutocompleteSuggestionsRequest` hooks. [#1161](https://github.com/elastic/search-ui/pull/1161)
+- Added support for `fuzziness: true` in `searchQuery` and `autocomplete`, enabling typo-tolerant matching. [#1159](https://github.com/elastic/search-ui/pull/1159)
+- Added support for range filters in the Elasticsearch Connector. [#1157](https://github.com/elastic/search-ui/pull/1157)
+- Introduced a dedicated entry point for `ApiProxyConnector` to optimize bundle usage. [#1146](https://github.com/elastic/search-ui/pull/1146)
+
+### 🧱 Changed
+
+- **React 19 Support:** Upgraded `react` and `react-dom` peer dependencies to version 19. [#1162](https://github.com/elastic/search-ui/pull/1162)
+
+### 🐛 Fixed
+
+- Fixed issue where queries with no matches would still return results from filters — filters are now applied in conjunction with matching queries. [#1151](https://github.com/elastic/search-ui/pull/1151)
+- Fixed incorrect behavior for facet filter types (`none`, `any`, `all`) in the Elasticsearch Connector. [#1153](https://github.com/elastic/search-ui/pull/1153)
+
+### 🧹 Removed
+
+- Fully removed the `searchkit` dependency from the Elasticsearch Connector. [#1143](https://github.com/elastic/search-ui/pull/1143)
+- Deprecated `postProcessRequestBodyFn` in favor of new `interceptSearchRequest`, `interceptAutocompleteResultsRequest`, `interceptAutocompleteSuggestionsRequest` hooks. [#1161](https://github.com/elastic/search-ui/pull/1161)
+
+### 🛠 Internal
+
+- Migrated CI from CircleCI to GitHub Actions.
+- Updated internal dev tooling: TypeScript, Jest, Replaced Enzyme with React Testing Library, ESLint, Prettier. [#1162](https://github.com/elastic/search-ui/pull/1162)
+- Minified production bundles using `tsup`, excluded source maps from production output. [#1148](https://github.com/elastic/search-ui/pull/1148)
+- Improved docs for Elasticsearch Connector, de-emphasized App Search and Workplace Search connectors. [#1149](https://github.com/elastic/search-ui/pull/1149)
+
+---
+
+## [1.23.0] - 2025-04-01
+
+### ✨ Added
+
+- Added the ability to preserve selected filters when performing a new search. This provides more flexibility in managing filter states between queries. [#1131](https://github.com/elastic/search-ui/pull/1131)
+ _Related to [#89](https://github.com/elastic/search-ui/issues/89)_
+- Introduced `useSearch` hook for React functional components. [#1130](https://github.com/elastic/search-ui/pull/1130)
+- Added `APIProxyConnector` to the Elasticsearch Connector to enable server-side integration using Node.js and Express. This enhances security by hiding API keys and other sensitive data. [#1126](https://github.com/elastic/search-ui/pull/1126)
+- Added TypeScript support to the sandbox example. [#1126](https://github.com/elastic/search-ui/pull/1126)
+- Updated sandbox structure, React version, and example organization. [#1126](https://github.com/elastic/search-ui/pull/1126)
+
+### 🐛 Fixed
+
+- Fixed export module compatibility issues by introducing bundling using `tsup`, ensuring correct behavior in both ESM and CommonJS environments. [#1114](https://github.com/elastic/search-ui/pull/1114)
+ _Fixes [#1046](https://github.com/elastic/search-ui/issues/1046)_
+- Fixed sorting logic when using `sortField` and `sortDirection` in state. Addressed inconsistencies in `setSort()` behavior. [#1112](https://github.com/elastic/search-ui/pull/1112)
+ _Fixes [#1109](https://github.com/elastic/search-ui/issues/1109)_
+- Fixed issue in `BooleanFacet` for numeric facet values (e.g., 0/1 or true/false), improving compatibility with Elasticsearch Connector. [#1111](https://github.com/elastic/search-ui/pull/1111)
+ _Fixes [#851](https://github.com/elastic/search-ui/issues/851)_
+
+### 🧹 Removed
+
+- Removed “Technical preview” label for Elasticsearch Connector as it is now generally available (GA). 🎉 [#1125](https://github.com/elastic/search-ui/pull/1125)
+- Deprecated `@elastic/search-ui-analytics-plugin` package. [#1120](https://github.com/elastic/search-ui/pull/1120)
+
+### 🛠 Internal
+
+- Switched to `tsup` for consistent module bundling across packages. [#1114](https://github.com/elastic/search-ui/pull/1114)
+- Applied shared TypeScript and bundling configurations across the repo. [#1114](https://github.com/elastic/search-ui/pull/1114)
diff --git a/CODEOWNERS b/CODEOWNERS
new file mode 100644
index 000000000..281aaa611
--- /dev/null
+++ b/CODEOWNERS
@@ -0,0 +1 @@
+* @elastic/search-experiences-team
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c0c3eca98..9294c39a8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,184 +1,123 @@
# Search UI Contributor's Guide
-Thank you for your interest in contributing to search-ui!
+Thank you for your interest in contributing to Search UI!
-How to build and contribute to Search UI.
+Before you begin, a couple notes...
-### Requirements
+- Prior to opening a pull request, please:
+ - Create an issue to [discuss the scope of your proposal](https://github.com/elastic/search-ui/issues).
+ - Sign the [Contributor License Agreement](https://www.elastic.co/contributor-agreement/). We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once.
+- Please write simple code and concise documentation, when appropriate.
-- Node: 10.16
-- NPM: 6.9
-- OS: Unix/Linux or Windows Subsystem for Linux
+**Contributing to the docs?** Refer to [docs/README.md](./docs/README.md).
+
+## Running Search UI
-### Mono-repo explanation
+### Codebase overview
This repository is maintained as a Monorepo using [Lerna](https://github.com/lerna/lerna).
Lerna configuration is contained in `lerna.json`.
-- `/packages` - Contains publishable search-ui npm packages.
-- `/examples` - Contains non-publishable examples of search-ui usage. They are declared
- as "packages" in `lerna.json` so that `npx lerna bootstrap` will automatically wire up the
+- `/packages` - Contains publishable Search UI npm packages.
+- `/examples` - Contains non-publishable examples of Search UI usage. They are declared
+ as "packages" in `lerna.json` so that yarn workspaces will automatically wire up the
examples to local dependencies.
-Because all examples are declared as "private", when running lerna commands other than bootstrap, (like `publish` and `test`), the `--no-private` flag should be appended.
-
Dependencies are declared in a package.json hierarchy.
- `/package.json` - Dependencies for repo tooling, like `husky` and `lerna`.
-- `/packages/package.json` - Common dev dependencies for all Search UI npm packages. Any dev Common dev dependencies for al that does not need to be called directly in a package level npm command
can be declared here.
- /`packages/{package_name}/package.json` - Package specific dependencies.
-Note that we do not encourage "hoisting" dependencies through lerna. This WILL
-cause the examples applications to error out from dependency version conflicts.
+### Requirements
+
+- Node: ^16.14.1
+- Yarn: ^1.2
+- OS: Unix/Linux or Windows Subsystem for Linux
### Installing dependencies
From the root level of this repository:
```shell
-npm install
+yarn
```
-Behind the scenes, this installs dependencies in the root folder, in the `packages` folder, and for each lerna package and example repo.
+Behind the scenes, yarn will installs dependencies in the root folder, and for each lerna package and example repo. Lerna is configured to use yarn workspaces which will hoist shared dependencies in the packages into the root.
### Building
-For all projects, run from project root. For single project, run from
-package root.
+For all packages, run from repository root. For single package, run from
+package folder.
```shell
-# Build
-npm run build
+# Build once
+yarn build
# Watch for changes and re-build
-npm run watch
+yarn watch
```
### Testing
-For all projects, run from project root. For single project, run from
-package root.
-
-All packages:
+For all packages, run from repository root. For single package, run from
+package folder.
```shell
-# from project root
-npm run test
+# Test once
+yarn test
# Watch for changes and re-run
-npm run test -- --watch
-```
-
-### Editor Setup
-
-#### VSCode
-
-We recommend using the ESLint plugin with the following settings:
-
-NOTE: We enable `formatOnSave` so that /examples projects are formatted automatically. eslint --fix
-would only apply to code under /packages
-
-```json
- "editor.formatOnSave": true,
- "eslint.enable": true
+yarn test -- --watch
```
### Sandbox
-The [sandbox](examples/sandbox/README.md) app can be used as a local development aid.
-
-### Branching Strategy
+The [sandbox app](examples/sandbox/README.md) is available to demo usage and act as a development aid.
-Our `master` branch holds the latest development code for the next release. If the next release will be a minor release, the expecation is that no breaking changes will be in `master`. If a change would be breaking, we need to put it behind a feature flag, or make it an opt-in change. We will only merge breaking PRs when we are ready to start working on the next major.
-
-All PRs should be created from a fork, to keep a clean set of branches on `origin`.
+It is wired up to use the local source of the Search UI libraries as dependencies via Lerna.
+This means as you update library code you can see it updated live in the sandbox app.
-Releases should be performed directly in master (or a minor branch for patches), following the Publishing guide below.
+To run it locally:
-We use a `stable` branch to indicate the latest release code.
-
-We will create branches for all minor releases.
-
-### Publishing
-
-Publish a new major or minor from master
-(Example, publishing 0.6.0)
-
-1. Run `npx lerna version 0.6.0 --force-publish --exact`.
-1. Verify the `0.6.0` tag was created as well as a "Release 0.6.0" commit.
-1. Run `nvm use` to make sure you are running the correct version of node, and verify that `npm run build` runs without error before publishing.
-1. Run `npx lerna publish from-package`.
-1. Verify the `0.6.0` has been published to npm.
-1. Verify that the `v0.6.0` tag and commit has been pushed to `master` on `origin`.
-1. Create new version branch, `0.6` from the `0.6.0` tag and push to `origin`.
-1. Create a release in Github.
-1. Close the release Milestone in Github.
-1. If this is the latest release, update the `stable` branch to this version `git checkout stable && git merge --ff-only master && git push origin`.
-1. Verify the demos on Netlify are functioning:
-
- https://search-ui-stable-elasticsearch.netlify.app/
- https://search-ui-stable-site-search.netlify.app/
- https://search-ui-stable.netlify.app/
-
-Publish a patch
-(Example, publish 0.6.1)
-
-1. Create a `0.6` branch from the `0.6.0` tag, if one does not already exist.
-1. Run `npx lerna version 0.6.1 --force-publish --exact`.
-1. Verify the `v0.6.1` tag was created as well as a "Release 0.6.1" commit.
-1. Run `nvm use` to make sure you are running the correct version of node, and verify that `npm run build` runs without error before publishing.
-1. Run `npx lerna publish from-package`.
-1. Verify the `0.6.1` has been published to npm.
-1. Verify that the `0.6.1` tag and commit has been pushed to `master` on `origin`.
-1. Cherry-pick the changes forward to subsequent minor releases and master, and repeat the process.
-1. Create a release in Github.
-1. Close the release Milestone in Github.
-1. If this is the latest release, update the `stable` branch to this version `git checkout stable && git merge --ff-only master && git push origin`.
-1. Verify the demos on Netlify are functioning:
-
- https://search-ui-stable-elasticsearch.netlify.app/
- https://search-ui-stable-site-search.netlify.app/
- https://search-ui-stable.netlify.app/
-
-### Canary releases for testing
+```shell
+# From the repository root
+# The project needs to be built before it is run
+# `yarn build` would also work in place of `yarn watch`
+yarn watch
+
+# In a separate terminal
+cd examples/sandbox
+yarn start
+```
-It can often be useful to publish a change and test it before doing a real live publish. For instance, it can be useful to publish something from a PR branch and test it with an actual install. Use lerna's [canary](https://github.com/lerna/lerna/tree/master/commands/publish#--canary)
-option for this.
+To configure the sandbox to use your own data, simply create a `.env` file
+in the sandbox folder, and configure the properties of the `connector` you're using.
-1. Check out pr branch
-1. `npx lerna publish --force-publish --canary --preid canary [patch|minor|major]` - Publishing with canary generates a unique new version number, publishes it to npm, then updates the `canary` tag in npm to point to that new version.
-1. In project you'll need to install all dependencies explicitly with the canary tag from npm:
+For example, if you're using App Search, put this into your `.env` file:
- ```
- npm install --save @elastic/react-search-ui@canary @elastic/search-ui-app-search-connector@canary @elastic/react-search-ui-views@canary search-ui-views@canary
- ```
+```
+REACT_APP_SEARCH_ENGINE_NAME=
+REACT_APP_SEARCH_KEY=
+REACT_APP_SEARCH_ENDPOINT_BASE=
+```
-1. To Deploy, simply push your changes to the `canary` branch, then visit "https://search-ui-canary.netlify.com/"
+### Editor Setup
-### Release candidates
+#### VSCode
-When pushing release candidates, the following lerna commands can be useful:
+We recommend using the ESLint plugin with the following settings:
-```
-# Create a pre-release version, like 1.0.0-rc.0
-npx lerna version [premajor | preminor | prepatch | prerelease] --exact --force-publish --no-private --preid rc
-# Publish 1.0.0-rc.0 and update the `next` to point to this version
-npx lerna publish from-package --force-publish --dist-tag next
+```json
+ "editor.formatOnSave": true,
+ "eslint.enable": true
```
-### Testing Canary build and Release Pre-releases
+NOTE: We enable `formatOnSave` so that `/examples` are formatted automatically. `eslint --fix` would only apply to code under `/packages`
-We have a number of demos available that you can use to do quick smoke testing of releases in various
-stacks:
+## Branching Strategy
-- https://codesandbox.io/s/search-ui-gatsby-example-u041m
-- https://codesandbox.io/s/search-ui-next-js-example-tb05u
-- https://codesandbox.io/s/search-ui-national-parks-example-kdyms
+Our `main` branch holds the latest development code for the next release. If the next release will be a minor release, the expecation is that no breaking changes will be in `main`. If a change would be breaking, we need to put it behind a feature flag, or make it an opt-in change. We will only merge breaking PRs when we are ready to start working on the next major.
-### Stable demos
-
-- Elastic App Search: https://search-ui-stable.netlify.com/
-- Elastic Site Search: https://search-ui-stable-site-search.netlify.com/
-- Elasticsearch: https://search-ui-stable-elasticsearch.netlify.com/
+All PRs should be created from a fork, to keep a clean set of branches on `origin`.
diff --git a/INTERNAL.md b/INTERNAL.md
new file mode 100644
index 000000000..a0e150598
--- /dev/null
+++ b/INTERNAL.md
@@ -0,0 +1,103 @@
+The content in this file links to Elastic internal resources and is mainly meant for core maintainers within Elastic. For a more general guide for developing, please consult CONTRIBUTING.md.
+
+# Running docs locally
+
+The Search UI docs are built using an internal library (which hopefully moves into the open soon!).
+
+An overview of the syntax used can be found here: https://github.com/elastic/docsmobile/blob/main/doc-site/docs/docs_syntax.mdx.
+
+1. Clone https://github.com/elastic/docs.elastic.co next to search-ui repo
+2. Create **content-dev.js** by moving into the `docs.elastic.co` folder and copying **content.js**: `cp config/content.js config/content-dev.js`
+3. Edit your **content-dev.js** file so that:
+ ```
+ sources: [
+ {
+ type: 'github',
+ location: 'elastic/wordlake',
+ },
+ {
+ type: 'file',
+ location: '../../search-ui'
+ }
+ ],
+ ```
+4. Run `yarn`, then `yarn init-docs`, then `yarn dev`.
+5. After the initial setup is done, simply use `yarn docs-start` from the search-ui root.
+
+# Publishing
+
+Releases should be performed directly in main (or a minor branch for patches), following the [Publishing guide](./PUBLISHING.md).
+
+We will create branches for all minor releases.
+
+> Because all examples are declared as "private", when running lerna commands other than bootstrap, (like `publish` and `test`), the `--no-private` flag should be appended.
+
+## Publish a new major or minor from main
+
+(Example, publishing 0.6.0)
+
+1. Run `npx lerna version 0.6.0 --force-publish --exact`.
+1. Verify the `0.6.0` tag was created as well as a "Release 0.6.0" commit.
+1. Run `nvm use` to make sure you are running the correct version of node, and verify that `npm run build` runs without error before publishing.
+1. Run `npx lerna publish from-package`.
+1. Verify the `0.6.0` has been published to npm.
+1. Verify that the `v0.6.0` tag and commit has been pushed to `main` on `origin`.
+1. Create new version branch, `0.6` from the `0.6.0` tag and push to `origin`.
+1. Create a release in Github.
+1. Close the release Milestone in Github.
+1. Verify the demo on Codesandbox is functioning: https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox
+
+## Publish a patch
+
+(Example, publish 0.6.1)
+
+1. Create a `0.6` branch from the `0.6.0` tag, if one does not already exist.
+1. Run `npx lerna version 0.6.1 --force-publish --exact`.
+1. Verify the `v0.6.1` tag was created as well as a "Release 0.6.1" commit.
+1. Run `nvm use` to make sure you are running the correct version of node, and verify that `npm run build` runs without error before publishing.
+1. Run `npx lerna publish from-package`.
+1. Verify the `0.6.1` has been published to npm.
+1. Verify that the `0.6.1` tag and commit has been pushed to `main` on `origin`.
+1. Cherry-pick the changes forward to subsequent minor releases and main, and repeat the process.
+1. Create a release in Github.
+1. Close the release Milestone in Github.
+1. Verify the demo on Codesandbox is functioning: https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox
+
+## Canary releases for testing
+
+It can often be useful to publish a change and test it before doing a real live publish. For instance, it can be useful to publish something from a PR branch and test it with an actual install. Use lerna's [canary](https://github.com/lerna/lerna/tree/master/commands/publish#--canary)
+option for this.
+
+1. Check out pr branch
+1. `npx lerna publish --force-publish --canary --preid canary [patch|minor|major]` - Publishing with canary generates a unique new version number, publishes it to npm, then updates the `canary` tag in npm to point to that new version.
+1. In project you'll need to install all dependencies explicitly with the canary tag from npm:
+
+ ```
+ npm install --save @elastic/react-search-ui@canary @elastic/search-ui-app-search-connector@canary @elastic/react-search-ui-views@canary
+ ```
+
+1. To check your changes, simply push them to the `canary` branch, then visit https://codesandbox.io/s/github/elastic/search-ui/tree/canary/examples/sandbox
+
+## Release candidates
+
+When pushing release candidates, the following lerna commands can be useful:
+
+```
+# Create a pre-release version, like 1.0.0-rc.0
+npx lerna version [premajor | preminor | prepatch | prerelease] --exact --force-publish --no-private --preid rc
+# Publish 1.0.0-rc.0 and update the `next` to point to this version
+npx lerna publish from-package --force-publish --dist-tag next
+```
+
+## Testing Canary build and Release Pre-releases
+
+We have a number of demos available that you can use to do quick smoke testing of releases in various
+stacks:
+
+- https://codesandbox.io/s/search-ui-gatsby-example-u041m
+- https://codesandbox.io/s/search-ui-next-js-example-tb05u
+- https://codesandbox.io/s/search-ui-national-parks-example-kdyms
+
+## Demo (uses code from main branch)
+
+- https://codesandbox.io/s/github/elastic/search-ui/tree/main/examples/sandbox
diff --git a/README.md b/README.md
index 7ea9227b7..994771150 100644
--- a/README.md
+++ b/README.md
@@ -1,323 +1,55 @@
-
+# [Elastic Search UI](https://docs.elastic.co/search-ui)
-> Libraries for the fast development of modern, engaging search experiences. :tada:
+A JavaScript library for the fast development of modern, engaging search experiences with [Elastic](https://www.elastic.co/). Get up and running quickly without re-inventing the wheel.
-## Contents
+**Check out the [documentation](https://docs.elastic.co/search-ui) to learn more about setting up and using Search UI.**
-- [About Search UI](#about-search-ui-rocket)
-- [Getting started](#getting-started-)
-- [Creating a search experience](#creating-a-search-experience)
-- [FAQ](#faq-)
-- [Contribute](#contribute-)
-- [License](#license-)
-
----
-
-## About Search UI :rocket:
-
-A **[React](https://reactjs.org)** library that allows you to quickly implement search experiences without re-inventing the wheel.
-
-Use it with [**Elastic App Search**](https://www.elastic.co/cloud/app-search-service?ultron=searchui-repo&blade=readme&hulk=product) or
-[**Elastic Site Search**](https://www.elastic.co/cloud/site-search-service?ultron=searchui-repo&blade=readme&hulk=product) to have a
-search experience up and running in minutes.
-
-### Features :+1:
+## 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.
-- **Headless** - Leverage our application logic, provide your own components or views.
- **Flexible front-end** - Not just for React. Use with any JavaScript library, even vanilla JavaScript.
-- **Flexible back-end** - Not just for Elastic App Search. Use with any backend.
-
-
-
-### Live Demo
-
-Checkout the [live demo of Search UI](https://search-ui-stable.netlify.com).
-
-[](https://codesandbox.io/s/national-parks-example-kdyms?fontsize=14)
-
-## Getting started 🐣
-
-Install **React Search UI** and the **App Search** connector.
-
-```sh
-# Install React Search UI and a Connector, like the Elastic App Search Connector
-npm install --save @elastic/react-search-ui @elastic/search-ui-app-search-connector
-```
-
-## Creating a search experience
-
-
-
-Use out of the box components, styles, and layouts to build a search experience in a matter of minutes.
-
-```jsx
-import React from "react";
-import AppSearchAPIConnector from "@elastic/search-ui-app-search-connector";
-import { SearchProvider, Results, SearchBox } from "@elastic/react-search-ui";
-import { Layout } from "@elastic/react-search-ui-views";
-
-import "@elastic/react-search-ui-views/lib/styles/styles.css";
-
-const connector = new AppSearchAPIConnector({
- searchKey: "search-371auk61r2bwqtdzocdgutmg",
- engineName: "search-ui-examples",
- endpointBase: "http://127.0.0.1:3002",
- cacheResponses: false
-});
-
-export default function App() {
- return (
-
-
- }
- bodyContent={}
- />
-
-
- );
-}
-```
-
-Or go "headless", and take complete control over the look and feel of your search experience.
-
-```jsx
-
- ({
- searchTerm,
- setSearchTerm,
- results
- })}
- >
- {({ searchTerm, setSearchTerm, results }) => {
- return (
-
- );
- }}
-
-
-```
-
-A search experience built with Search UI is composed of the following layers:
-
-1. [A Search API](#1-search-api)
-2. [A Connector](#2-connectors)
-3. [A SearchProvider](#3-searchprovider)
-4. [Components](#4-components)
-5. [Styles and Layout](#5-styles-and-layout)
-
-```
-Styles and Layout -> Components -> SearchProvider -> Connector -> Search API
-```
-
----
-
-### 1. Search API
-
-A Search API is any API that you use to search data.
-
-We recommend [**Elastic App Search**](https://www.elastic.co/cloud/app-search-service?ultron=searchui-repo&blade=readme&hulk=product).
-
-It has Elasticsearch at its core, offering refined search UIs, robust documentation, and accessible dashboard tools.
-
-You can start a [14 day trial of the managed service](https://www.elastic.co/cloud/app-search-service?ultron=searchui-repo&blade=readme&hulk=product) or [host the self managed package for free](https://www.elastic.co/downloads/app-search?ultron=searchui-repo&blade=readme&hulk=product).
-
-Once your data is indexed into App Search or a similar service, you're good to go.
-
-### 2. Connectors
-
-A connector is a module that tell Search UI how to connect and communicate with your Search API.
-
-It generates Search API calls for you so that Search UI will "just work", right out of the box.
-
-```js
-const connector = new AppSearchAPIConnector({
- searchKey: "search-371auk61r2bwqtdzocdgutmg",
- engineName: "search-ui-examples",
- hostIdentifier: "host-2376rb"
-});
-```
+- **Flexible back-end** - Use it with Elasticsearch, Elastic Enterprise Search, or any other search API.
-_Read the [advanced README](./ADVANCED.md#build-your-own-connector) to learn how to build a connector for any Search API._
+## Live demos 👀
-### 3. SearchProvider
+### Connectors
-`SearchProvider` is the top level component in your Search UI implementation.
+- [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)
-It is where you configure your search experience and it ties all of your components together, so that they work as a cohesive application.
+### Examples
-```jsx
-
-
{/* Place Components here! */}
-
-```
-
-While components can be handy, a search experience can have requirements that don't quite fit what components provide "out of the box". Use `WithSearch` to access "actions" and "state" in a [Render Prop](https://reactjs.org/docs/render-props.html), giving you maximum flexibility over the experience.
-
-```jsx
-
- ({
- searchTerm,
- setSearchTerm
- })}
- >
- {({ searchTerm, setSearchTerm }) => (
-
{/* Work directly with state and actions! */}
- )}
-
-
-```
-
-_Read the [Advanced Configuration Guide](./ADVANCED.md#advanced-configuration) or learn more about the state management and the [Headless Core](./ADVANCED.md#headless-core)._
-
-### 4. Components
+- [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)
-Components are the building blocks from which you craft your search experience.
+## Get started
-Each Component - like `SearchBox` and `Results` - is a child of the `SearchProvider` object:
+### Installation
-```jsx
-
-
+
+```
+
+## 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/reference/api-react-with-search.md b/docs/reference/api-react-with-search.md
new file mode 100644
index 000000000..c1458f70f
--- /dev/null
+++ b/docs/reference/api-react-with-search.md
@@ -0,0 +1,86 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/search-ui/current/api-react-with-search.html
+applies_to:
+ stack:
+ serverless:
+---
+
+# WithSearch & withSearch [api-react-with-search]
+
+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.
+
+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.
+
+Both methods expose a `mapContextToProps` function which allows you to pick which state and actions from context you need to work with.
+
+## 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 |
+| ------- | ------ | ------------------- |
+| context | Object | The current Context |
+| props | Object | The current props |
+
+ex.:
+
+```jsx
+import { withSearch } from "@elastic/react-search-ui";
+
+const Component = ({ searchTerm, setSearchTerm }) => {
+ return (
+