# Tutorial: How To Build A Spotlight Like Search And Navigation Experience
Your Searchbar is the most powerful widget on your site! Offer a SoTA search Ux similar to Spotlight, Chrome, Google, Amazon by integrating search, navigation and the ability to run custom JavaScript functions from right within your searchbar.
In this tutorial, I will show how to achieve using the SearchBox UI component of ReactiveSearch, an Apache 2.0 licensed search UI kit that works out-of-the-box with search engines such as Elasticsearch, OpenSearch, and MongoDB Atlas Search.
## Beyond Search Box
Use cases for using the searchbox component in your application:
- **In-app navigation**: Offer an in-app navigation experience through your searchbar allowing users to navigate through your site or dashboard without needing to jump between multiple menus, or relying on header/footer navigations.
- **Onboarding of new users**: New users who are not familiar with the product or how to use it can just go to the search bar and search for the documentation of the product or search for help if needed. Through the in-app navigation, a user can search for frequently asked questions and navigate to the page effortlessly.
- **User productivity with actions**: When actions like toggling between light mode or dark mode of your app can be done directly from the search bar, it can further enhance the search user experience.
## Things You Need
### Configuring Reactivesearch for use with React:
[Reactivesearch](https://github.com/appbaseio/reactivesearch) is an Elasticsearch UI component library. It is an open-source library that offers rich and highly customizable UIs that can be used to index Elasticsearch hosted anywhere. We will be using the search box UI provided by Reactivesearch with React to build the spotlight-like search experience.
![reactivesearch.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1654125442831/GEyKJOJPM.png align="left")
### Postman for making API requests:
[Postman](https://www.postman.com/) is an application used for API testing. It is an HTTP client that tests HTTP requests, utilizing a graphical user interface, through which we obtain different types of responses that need to be subsequently validated. We will be leveraging on making API requests to an endpoint to store our required fields for our search box.
## Implementing the SearchBox
### Step 1: Setup
**Create React App**
So let's start by making sure we have node installed on our computer. You can use the command below to check if you have it installed. If you don't, you can install it by [clicking here](https://nodejs.org/en/download/)
```
node -v
// OR
node --version
```
After installing node on our computer, let's start creating our project. Go into your desired directory and install react. We will be using the popularly known [create-react-app](https://reactjs.org/docs/create-a-new-react-app.html) to initialize our project. Use the command below in your terminal to install react.
```
npx create-react-app spotlight-search
cd spotlight-search
npm start
```
> Note: npx comes with npm 5.2+ and higher, see instructions for an older release [here](https://blog.reactivesearch.io/react-search-ui-tutorial).
After creating your react app, it comes with a great folder structure like the one below.
```
spotlight-search
├── README.md
├── node_modules
├── package.json
├── .gitignore
├── package-lock.json
├── public
│ └── favicon.ico
│ └── index.html
│ └── manifest.json
└── src
└── App.css
└── App.js
└── App.test.js
└── index.css
└── index.js
└── logo.svg
└── registerServiceWorker.js
```
**Install Reactive Search**
Next, we will be installing the ReactiveSearch library using the command below on our terminal
```
npm install @appbaseio/reactivesearch
```
You can clone the app directly from [github here](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-1-project-setup)
This is the current state of our app below
%[https://codesandbox.io/embed/github/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-1-project-setup?fontsize=14&hidenavigation=1&theme=dark]
### Step 2: Building Components
**ReactiveBase Component**
We will use the ReactiveBase component to wrap our whole application in *./src/app.js*. ReactiveBase is a container component provided to bind the backend (data source) and the UI components to enable them to interact effectively when there is a change in the data.
```
import { ReactiveBase } from '@appbaseio/reactivesearch';
function App() {
return (
);
}
export default App
```
> Note: The ``url`` passed in the ```` is a sample credential and not going to work unless generated from the appbase website
From the props passed into the ReactiveBase the most important, we will be talking about is the ``url``. The ``url`` is connecting our frontend with our backend to allow communication between the client-side and the server or data source. For this tutorial, we will be creating and hosting our data on the [appbase](https://www.appbase.io/) app. Create an [appbase](https://www.appbase.io/) account and follow the instructions to create a cluster. You can manage your data set graphically using [dejavu](https://opensource.appbase.io/dejavu/) by providing the ``url`` and *app name* in the fields given in the app. For this app, you can view the data set by following [this link](https://dejavu.appbase.io/?appname=good-books-ds&url=https://04717bb076f7:be54685e-db84-4243-975b-5b32ee241d31@appbase-demo-ansible-abxiydt-arc.searchbase.io&mode=view)
Refer to the [github page](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-2-adding-reactivebase) to clone the current state of the app.
You can read more about the other props by visiting the appbase documentation on [ReactiveBase](https://docs.appbase.io/docs/reactivesearch/v3/overview/reactivebase/)
**SearchBox Component**
```` is a component used in building the interface for a search box. It offers a lightweight and performant Searchbox UI that can search on an index as well as offer search and navigation on curated suggestions.
```
```
Below I will briefly talk about some of the props supplied to the search box and their functions.
- **dataField**: The ``dataField`` takes an array of strings that can be used to specify which field in the database is being searched when the query is passed.
- **enablePopularSuggestions** and **popularSuggestionsConfig**: This is used to specify how popular searches are displayed on the suggestion section of the search bar. It also applies to the other suggestions like the recent and predictive suggestions
- **size**: The ``size`` value is used to specify how many suggestions in total are being displayed. The default is 10 but can be changed based on what suits your needs.
- **innerClass**: The ``innerClass`` prop can be used to access each field in the search box which can help us in styling how we want our search UI looks.
You can read more about the [SearchBox here](https://docs.appbase.io/docs/reactivesearch/v3/search/searchbox/).
The sandbox below is the state of our app after adding the search box
%[https://codesandbox.io/embed/github/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-3-adding-searchbox?fontsize=14&hidenavigation=1&theme=dark]
### Step 3: Introduction to featuredSuggestions
The ``featuredSuggestions`` prop is the newly added functionality for the ```` component where it comes with a variety of use cases but most importantly improves the user experience of our application. Below I will show you how to add and use the prop in our book search website we have created so far. The highlight of what we will be doing is adding a function to toggle between the light and dark mode of our website, navigating to an external link on a new page, and adding a function to trigger an alert on the window of the browser.
Going back to our ```` component, we are going to add an extra prop to enable the ``featuredSuggestions`` and ingest our data from an external source.
```
enableFeaturedSuggestions={true}
featuredSuggestionsConfig={{
featuredSuggestionsGroupId: 'spotlight-search', // # mandatory
maxSuggestionsPerSection: 10,
sectionsOrder: ['repositories', 'docs', 'functions'],
}}
```
After adding this block of code, our search box will have a different but aesthetic look. The picture below illustrates how our search box is displayed when expanded.
![Screenshot 2022-06-07 at 11-57-38 React App.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1654731753967/rEMizkdd9.png align="left")
Next, I will be explaining what the props of the ``featuredSuggestions`` are and I will take you through how to add the new functionalities to your ```` component.
- **enableFeaturedSuggestions**: This prop tells the ```` to enable the use of the ``featuredSuggestions`` feature for our search bar. It takes in a boolean value which that is either true or false. To use the ``featuredSuggestions``, we set the value to true as seen above.
- **featuredSuggestionsConfig**: This takes the configuration of how we want to structure our omnibar which gives us the spotlight experience which enhances our search bar and gives the user ease in navigating throughout our webpage and beyond. This prop takes a series of arguments wrapped into double curly braces. I will further break down those attributes in the next section.
### Step 4: Styling our component
To give our application a unique look to make it stand out and also appeal to our users, I decided to create a custom styling that targets the tags and class names given in our component building stage.
The CSS styling below is linked to our app to give it a unique look as you will also see in a sandbox shortly.
```
body {
max-width: 1200px;
margin: 0 auto;
padding-top: 15px;
padding-inline:15px;
}
.test-suggestion img {
height: 25px;
max-height: 25px !important;
}
.active-test-suggestion img {
height: 25px;
max-height: 25px !important;
}
.section-header h2{
margin:0;
}
```
So here we are, we have built the interface of our application. Below is a sandbox showing the progress of what our application currently is.
### Step 5: Details about building featuredSuggestions
To create the ``featuredSuggestions`` section in our application, we need to perform a request to a backend API that is going to populate our featured suggestions section or the omnibar section. Below we have a cURL making a PUT request to a backend endpoint.
```
curl --location -g --request PUT 'http://{{user}}:{{password}}@{{host}}/_featured_suggestions_group/{{featured_suggestions_group_id}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"sectionLabels": {
"repositories": {
"label": "Repositories
"
},
"docs": {
"label": "Documentation
"
},
"functions": {
"label": "Functions
"
}
},
"suggestions": [
{
"label": "@appbaseio/reactivesearch
",
"value": "reactivesearch repository",
"description": "Github repository for reactivesearch",
"action": "navigate",
"subAction": "{\"link\": \"https://github.com/appbaseio/reactivesearch\", \"target\": \"_blank\" }",
"sectionId": "repositories",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 1
},
{
"label": "@appbaseio/reactivesearch-vue
",
"value": "reactivesearch repository for vuejs",
"description": "Github repository for reactivesearch-vue",
"action": "navigate",
"subAction": "{\"link\": \"https://github.com/appbaseio/reactivesearch/tree/next/packages/vue\", \"target\": \"_blank\" }",
"sectionId": "repositories",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 2
},
{
"label": "@appbaseio/react-searchbox
",
"value": "appbase react-searchbox repository",
"description": "Github repository for react-searchbox",
"action": "navigate",
"subAction": "{\"link\": \"https://github.com/appbaseio/searchbox/tree/master/packages/react-searchbox\", \"target\": \"_blank\" }",
"sectionId": "repositories",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 3
},
{
"label": "@appbaseio/vue-searchbox
",
"value": "appbase vue-searchbox repository",
"description": "Github repository for vue-searchbox",
"action": "navigate",
"subAction": "{\"link\": \"https://github.com/appbaseio/searchbox/tree/master/packages/vue-searchbox\" , \"target\": \"_blank\"}",
"sectionId": "repositories",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 4
},
{
"label": "@appbaseio/reactivesearch
",
"value": "reactivesearch repository",
"description": "Documentation for reactivesearch",
"action": "navigate",
"subAction": "{\"link\": \"https://docs.appbase.io/docs/reactivesearch/v3/overview/quickstart\", \"target\": \"_blank\" }",
"sectionId": "docs",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 1
},
{
"label": "@appbaseio/reactivesearch-vue
",
"value": "documentation for vuejs reactivesearch",
"description": "Documentation for reactivesearch-vue",
"action": "navigate",
"subAction": "{\"link\": \"https://docs.appbase.io/docs/reactivesearch/vue/overview/QuickStart\", \"target\": \"_blank\" }",
"sectionId": "docs",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 2
},
{
"label": "@appbaseio/react-searchbox
",
"value": "appbase react-searchbox docs",
"description": "Documentation for react-searchbox",
"action": "navigate",
"subAction": "{\"link\": \"https://docs.appbase.io/docs/reactivesearch/react-searchbox/quickstart\", \"target\": \"_blank\" }",
"sectionId": "docs",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 3
},
{
"label": "@appbaseio/vue-searchbox
",
"value": "appbase vue-searchbox docs",
"description": "Documentation for vue-searchbox",
"action": "navigate",
"subAction": "{\"link\": \"https://docs.appbase.io/docs/reactivesearch/vue-searchbox/quickstart\" , \"target\": \"_blank\"}",
"sectionId": "docs",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 4
},
{
"label": "Alert
",
"value": "alert",
"description": "Invokes an alert message",
"action": "function",
"subAction": "function() { alert('Hello World! with theme');}",
"sectionId": "functions",
"iconURL": "https://www.svgrepo.com/show/281847/bell.svg",
"order": 1
},
{
"label": "Light
",
"value": "light mode",
"description": "Change theme to light mode",
"action": "function",
"subAction": "function(){ window.history.pushState({ theme: 'white'}, '', '/light');window.location.reload();}",
"sectionId": "functions",
"iconURL": "https://www.svgrepo.com/show/20546/sun.svg",
"order": 2
},
{
"label": "Dark
",
"value": "dark mode",
"description": "Change theme to dark mode",
"action": "function",
"subAction": " function(){ window.history.pushState({ theme: 'dark'}, '', '/dark');window.location.reload();}",
"sectionId": "functions",
"iconURL": "https://www.svgrepo.com/show/8265/moon.svg",
"order": 3
},
{
"label": "Search on Google
",
"value": "google search",
"description": "Search keyword on google",
"action": "function",
"subAction": "function() {window.open('https://www.google.com');}",
"sectionId": "functions",
"iconURL": "https://www.svgrepo.com/show/122724/google.svg",
"order": 4
}
]
}'
```
**The endpoint**
The endpoint is used to create or update the list of featured suggestions. In our case, our endpoint will look like the example below:
```
'https://c3416aa3be0a:1dca7a12-f050-45a7-80e8-d9f296a06e4f@appbase-demo-ansible-abxiydt-arc.searchbase.io/_featured_suggestions_group/spotlight_search'
// Compare the above and below
'http://{{user}}:{{password}}@{{host}}/_featured_suggestions_group/{{featured_suggestions_group_id}}'
// the {{user}}:{{password}}@{{host}} is simply our url from the ReactiveBase container component above
```
The endpoint takes in a ``featured_suggestions_group_id`` that can be anything based on your preference. Using this endpoint perform, a PUT request on postman or any other API testing platform of your choice.
You will pass a body which mainly consists of two main parts **sectionLabels** and
**suggestions**.
> The appbase.io team is working on providing a GUI for ingesting the featured suggestions which will make it possible to add featured suggestions with a point-and-click control plane.
**The body**
The body of our request is very vital in this article. Therefore, I will take my time to explain everything using simple terms to make it easy to create one. The body from the above request is written in JSON format, it is passed to the request endpoint body. The body is categorized into two main parts:
- **sectionLabels**: The section label is used to tell the user what a particular section in the search bar is doing. It helps the user understand what action is performed when he interacts with a component. Below are the section labels from our cURL:
```
"sectionLabels": {
"repositories": {
"label": "Repositories
"
},
"docs": {
"label": "Documentation
"
},
"functions": {
"label": "Functions
"
}
},
```
We have three main sections from the above ``repositories``, ``docs``, and ``functions``. The label which is enclosed within the curly braces is what the user sees when using the UI.
- **suggestions**: The suggestions are an array that contains all your suggestions and the necessary values needed to display the props, It has different values like the ``label``, ``value``, ``action``, and so on.
Below we have a sample from our suggestions array above:
```
{
"label": "@appbaseio/vue-searchbox
",
"value": "appbase vue-searchbox repository",
"description": "Github repository for vue-searchbox",
"action": "navigate",
"subAction": "{\"link\": \"https://github.com/appbaseio/searchbox/tree/master/packages/vue-searchbox\" , \"target\": \"_blank\"}",
"sectionId": "repositories",
"iconURL": "https://camo.githubusercontent.com/95874e325a752e6ffb604991feb719c6e8bae6a552ed23d4a566bc4d518bc090/68747470733a2f2f692e696d6775722e636f6d2f696952397741732e706e67",
"order": 4
},
```
Below we have the definition of the necessary values in a suggestion.
- **label**: The ``label`` is used to display the name of the suggestion, it accepts HTML and a string depending on how you want the element to be displayed.
- **value**: The ``value`` element is used to give the suggestion a unique value.
- **description**: The ``description`` value is used to display a mini description under a suggestion for more clarification for the user.
- **action**: The ``action`` is a very essential part of the suggestion. It takes two values ``navigate`` and ``function``.
When ``navigate`` is passed as the action, it identifies that the suggestion is a link element that can be used to navigate through the website or even access an external link. The ``function`` is passed into the action when you have an intention to perform or trigger a function on the website. This function can range from displaying an alert to changing certain flows of the website like toggling between light and dark mode.
- **subAction**: This depends on the action provided. If the provided action is ``navigate`` then we have to pass a link to the subAction like the below illustration
```
"subAction": "{\"link\": \"https://docs.appbase.io/docs/reactivesearch/vue-searchbox/quickstart\" , \"target\": \"_blank\"}"
```
it takes a ``link`` pointing to the location of the suggestion and a ``target`` value to either open the link on a new page when ``_blank`` is passed or open it on the same page when ``self`` is passed as the ``target``.
The second action is ``function``, when this is passed the ``subAction`` now takes in a function to perform an action on the website. The below illustration shows an example of a function to display an alert
```
"subAction": "function(currentSuggestion, inputValue, customEvents) { alert('Hello World! with theme');}"
```
1. `currentSuggestion` is the currently selected suggestion item. It's an object having information about the suggestion.
2. `inputValue` is the current input value of the SearchBox.
3. `customEvents` is a key-value pair object that is injected via the `ReactiveBase` component as depicted below.
```
```
- **sectionId**: This takes the value where we want our suggestion to appear. For the ``sectionId``, you pass any value that is present in the ``sectionLabels``. The suggestion is going to appear among the values in a particular section.
- **iconURL** or **icon**: Next, we want to have an icon that will be shown beside our suggestion. We can achieve this in two ways. we can use the ``iconURL`` for passing an external link to the icon we want to display or use the ``icon`` to pass an HTML tag for our icon. The illustration below shows an example of the two use cases
```
"iconURL": "https://www.svgrepo.com/show/281847/bell.svg",
// OR
"icon": "
" alt='icon description' height='10' width='10' /> "
```
- **order**: This simply takes the order in terms of relevance we want to display each suggestion in a section.
You can get the full body of the [request here](https://github.com/appbaseio-apps/saas-search-searchbox/blob/main/steps/step-5-adding-featured-suggestion/src/test.json)
### Step 6: Connecting Everything
Finally, to put everything together, We'll go to the postman and make our request. Make the PUT request to your endpoint based on your credentials gotten from [appbase](https://www.appbase.io/) app.
We are going to get a response returning the ``featured_id`` we supplied. We will then use that id in our ``featuredSuggestion`` prop.
```
featuredSuggestionsConfig={{
featuredSuggestionsGroupId: 'spotlight', // id returned after the request.
maxSuggestionsPerSection: 10,
sectionsOrder: ['repositories', 'docs', 'functions'],
}}
```
Our final app will look like the below sandbox now.
%[https://codesandbox.io/embed/github/appbaseio-apps/saas-search-searchbox/tree/main/steps/final-app?fontsize=14&hidenavigation=1&theme=dark]
You can also access the code on [github here](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-5-adding-featured-suggestion)
## Live Demo and Code
Finally, We have reached the end of our book search app which comes with a spotlight search experience that can give an incredible user search experience. You can access the [live site here](https://spotlight-search.vercel.app/) and the full code is on github which can be [accessed here](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/final-app).
## Summary
Here is a summary of all the steps we covered in this tutorial to build a Spotlight like search experience with the SearchBox UI component:
- [Step 1: Project Setup](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-1-project-setup)
- [Step 2: Adding Provider component](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-2-adding-reactivebase)
- [Step 3: Adding SearchBox UI component](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-3-adding-searchbox)
- [Step 4: Styling the SearchBox UI](https://github.com/appbaseio-apps/saas-search-searchbox/blob/main/steps/step-4-adding-style/src/App.css)
- [Step 4: Adding curated suggestions with featuredSuggestions](https://github.com/appbaseio-apps/saas-search-searchbox/tree/main/steps/step-5-adding-featured-suggestion)
If you enjoyed this tutorial, you should 🌟 the [ReactiveSearch UI project over here](http://github.com/appbaseio/reactivesearch).