Creating an omnibar with Autocomplete.js
Tags: javascript, ux, tutorial, react
Published: 2021-09-08 15:17:55


When is a search bar not a search bar? When it's an "omnibar" built with Autocomplete!

{% youtube ghy7a78JGCQ %}

In her [episode of Learn with Jason](https://www.learnwithjason.dev/javascript-autocomplete), [Sarah Dayan](https://twitter.com/frontstuff_io) mentioned the idea of using Autocomplete to create an experience brimming with shortcuts and power-user affordances.

In this tutorial, we'll walk through setting up [Autocomplete](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete/) to fire interactions with JavaScript. Specifically, we'll build an omnibar to toggle light and dark mode for our website. An omnibar is a search field that has both search and actions that can be taken. A strong example of this is the Chrome or Firefox search and URL bar.


In the search field, a user will be able to type in `/` commands. These commands will be tied to specific JavaScript methods to trigger. We'll also make the Autocomplete results stateful. When the app is in light mode, the light mode option will show an "enabled" flag. When dark mode is enabled, the dark mode option will show the flag.

Give it a try yourself!

{% codesandbox autocomplete-actions-finished-eh7xw %}

## Configuring Autocomplete for use with React

At its core, Autocomplete is a vanilla JavaScript library. Let's make it a bit more reusable by mounting it as a React component for use in any React-based framework or site.

We'll start with CodeSandbox's basic React sandbox. [Fork this sandbox](https://alg.li/omnibar-starter) to get the exact starting point with all packages installed for us.

To create our component, we'll start by adding a new file named `Autocomplete.js`. This file will house all the initialization code for the Autocomplete library and export the component for use in our application.

At the top of the new file, import the necessary elements from React, React-dom, and the Autocomplete libraries.

```javascript
import React, { createElement, Fragment, useEffect, useRef } from "react";  
import { render } from "react-dom";  
import { autocomplete } from "@algolia/autocomplete-js";
```

Once imported, we need to export a new functional React component. We'll start with the basic boilerplate for creating a new mounted component.

```javascript
export function Autocomplete(props) {  
  const containerRef = useRef(null);  
  
  useEffect(() => {  
    if (!containerRef.current) {  
      return undefined;  
    }
    
    
    // Space to initialize autocomplete on the newly created container
    
    
    // Destroy the search instance in cleanup  
    return () => {  
      search.destroy();  
    };  
    
  }, [props]);
  
  return <div ref={containerRef} />;  
}
```

This code will take care of the basic initialization and breakdown of the component on mount and unmount.

Inside the function, it's time to initialize the Autocomplete instance.

```javascript
// Creates an Autcomplete component from the JS library
// https://www.algolia.com/doc/ui-libraries/autocomplete/guides/using-react/
export function Autocomplete(props) {
  const containerRef = useRef(null);
  
  useEffect(() => {
    if (!containerRef.current) {
      return undefined;
    }
    
    // Initialize autocomplete on the newly created container
    const search = autocomplete({
      container: containerRef.current,
      renderer: { createElement, Fragment },
      // Autocomplete render()
      // https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete/#param-render
      render({ children }, root) {
        // react-dom render
        // https://reactjs.org/docs/react-dom.html#render
        render(children, root);
      },
      ...props
    });
    
    // Destroy the search instance in cleanup
    return () => {
      search.destroy();
    };
  }, [props]);
  
  return <div ref={containerRef} />;
}
```

The `autocomplete` method accepts an object of options. We set the `container` property to be the element created by this function. By specifying the `renderer` function, we can use React's `createElement` method and `Fragment` component.

Then, we need to provide Autocomplete with a `render` function. This function will accept an object of components to render (`children`), and the element to attach the instance (`root`). 

We can then use any method to render these items. In our case, we'll use `react-dom`'s `render()` method and pass it those same elements. Finally, we want to pass the `autocomplete` method any additional props added to our component when we use it. This will allow for on-the-fly customizations.

## Using the `<Autocomplete />` component

Moving to the `App.js` file, we can import our Autocomplete component (along with some default styling).

```javascript
// Styles
import "./styles.css";  
import "@algolia/autocomplete-theme-classic";  

// Import algolia and autocomplete needs
import { Autocomplete } from "./Autocomplete";
```

From here, we're ready to put an Autocomplete field on the page. Inside the `App()` function's JSX return value, we can put the `<Autocomplete />` component anywhere that makes sense for the UI. I suggest right after the main text of the page.

```javascript
export default function App() {  
  return (  
    <div className="App">  
         <h1 className="text-xl">  
           Run JS from{" "}  
           <a href="https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete/">  
             Autocomplete  
           </a>  
         </h1>  
         <p className="text-base">  
           This demo is based on the amazing idea of{" "}  
           <a href="https://twitter.com/frontstuff_io">Sarah Dayan</a> in her  
           appearance on{" "}  
           <a href="https://www.learnwithjason.dev/javascript-autocomplete">  
             Learn with Jason  
           </a>  
           .  
         </p>  
         <p>  
           Use the Autocomplete box below to toggle dark mode and perform other  
           JS-driven actions on the page.  
         </p>  
    
          <Autocomplete />
    
    {/* ... the rest of the function ... */}
    </div>
  )
}
```

The Autocomplete component can accept any prop that the `autocomplete-js` library can accept as an option. To start, let's add placeholder text.

```jsx
<Autocomplete placeholder="Try /dark" />
```

A search field should appear in our app with the placeholder text set. This field doesn't do anything yet. Let's add some data to complete.

## Adding an `actions` source to the Autocomplete component

The Autocomplete library is capable of creating autocomplete functionality against multiple sources. In our case, we'll only have one static source, but any external data – including Algolia indices – can be used to populate this functionality.

To add a source, we'll use the `getSources` prop and provide a function that accepts the `query` option. This query is what a user is actively typing into the input. We can use this to check against the items in our data.

A source is an object in the getSources returned array. The basic elements we need for the source are a `sourceId` string, a `template` object for rendering, and a `getItems()` function that returns the data. For now, we'll just return a static array with a label attribute. This is enough to populate our autocomplete. Let's also add `openOnFocus` as a prop to automatically list our items when a user focuses the field.

```javascript
<Autocomplete  
  placeholder="Try /dark"
  openOnFocus   
  getSources={({ query }) => [  
    {  
      sourceId: "actions",  
      templates: {  
        item({ item }) {  
          return <h3>{item.label}</h3>  
        }  
      },  
      getItems({ state }) {  
        return [  
          {  
            label: "/dark"  
          },  
          {  
            label: "/light"  
          }  
        ]  
      }  
    }  
  ]}  
/>
```

Now, we have items populating our field, but we're not filtering items as we type. Let's fix that with a couple helper functions.

## Filtering and highlighting Autocomplete items

When using an Algolia index, we can use some helper functions to manage filtering and highlighting, but we're not using an Algolia index. In our use case, we want to keep this fully in the browser. To do this, we need a couple helper functions to properly filter and highlight our options.

### Filtering Autocomplete items with JavaScript RegExp()

JavaScript offers the ability to filter an array based on a regular expression test. To do that, we need to create a pattern to test against for any combination the user can throw at us. Let's create a helper function based on the query and use that in a JS `.filter()` method.

In `App.js` outside the export, we'll create the new helper function `getQueryPattern()`.

```javascript
function getQueryPattern(query, flags = "i") {  
  const pattern = new RegExp(  
    `(${query  
      .trim() // Trim leading and ending whitespace 
      .toLowerCase() // convert to lower case
      .split(" ") // Split on spaces for multiple commands 
      .map((token) => `^${token}`) // Map over the resulting array and create Regex_  
      .join("|")})`, // Join those expressions with an OR | 
    flags  
  );
  
  return pattern;  
}

export default function App() { /* ... */ } 
```

Once the helper function is created, we'll create the pattern in the `getItems()` method before we return the array of items.

With the pattern saved, we can test our array against it.

```javascript
<Autocomplete
  placeholder="Try /dark"
  openOnFocus
  getSources={({ query }) => [
    {
      sourceId: "actions",
      templates: {
        item({ item }) {
          return <h3>{item.label}</h3>
        }
      },
      getItems({ state }) {
        const pattern = getQueryPattern(query);

        return [
          {
            label: "/dark"
          },
          {
            label: "/light"
          }
        ].filter(({ label }) => pattern.test(label)) // tests the label against the pattern
      }
    }
  ]}
/>
```

Now, when we type `/dark` into the field, only the `/dark` option. We haven't given the user any indication of why that works. Let's add a small highlighting function to showcase the letters typed.

### Highlighting the string being typed in results

In order to highlight the typed text, we need to take the query text and the pattern we created in the last step and generate a new string that adds additional markdown around the typed text.

Right after the `getQueryPattern` helper function, let's create a new `highlight` helper function.

```javascript
function highlight(text, pattern) {

  // Split the text based on the pattern  
  const tokens = text.split(pattern);

  // Map over the split text and test against the pattern  
  return tokens.map((token) => {

    // If the pattern matches the text, wrap the text in <mark>  
    if (!pattern.test("") && pattern.test(token)) {
      return <mark>{token}</mark>;
    }

    // return the token back to the array  
    return token;
  });
}
```

This helper function takes the text to test and the pattern to check it against and returns a string with additional markup.

We start by splitting the text based on the pattern. This will give us an array with two parts – matched and unmatched. As we map over this new array, we can check the text against the pattern and if it matches, wrap that specific item in a new piece of markup. If it doesn't, return the unmodified text.

```javascript
<Autocomplete
  placeholder="Try /dark"
  openOnFocus
  getSources={({ query }) => [
    {
      sourceId: "actions",
      
      templates: {
        item({ item }) {
          return <h3>{item.highlighted}</h3>
        }
      },
      
      getItems({ state }) {
        const pattern = getQueryPattern(query);

        return [
          {
            label: "/dark"
          },
          {
            label: "/light"
          }
        ]
        .filter(({ label }) => pattern.test(label)) // tests the label against the pattern
        .map((action) => ({
          ...action,
          highlighted: highlight(action.label, pattern)
        }));
      }
    }
  ]
  }
/>
```

With that helper function, we can now map over all the filtered items. We'll take the action item and return back an object with all of its initial properties, but a new `highlighted` property that contains our highlighted text. This is built from the action's `label` property and the pattern we defined earlier. 

Now instead of using the `action.label` in our template, we'll change it to use the new `highlight` property. When `/dark` is typed into the field, the item will have properly highlighted text.

The filtering UI is complete, but when we select an item, nothing happens. Let's fix that.

## Firing a JavaScript function in Autocomplete with `onSelect`

Each source in the `getSources` array can have its own `onSelect` method. This method defines the functionality for when a user selects an option – via keyboard or click.

Let's start by making a global select function to log the item's data and then reset the query to a blank string.

```javascript
getSources = {({ query }) => [
  {
    sourceId: "actions",
    templates: {
      item({ item }) {
        return <h3>{item.highlighted}</h3>
      }
    },
    // Run this code when item is selected  
   onSelect(params) {
      // item is the full item data
      // setQuery is a hook to set the query state
      const { item, setQuery } = params;
      console.log(item)
      setQuery("");
    },
  }
```

For one action, we could define the JavaScript in this method, but to make this reusable for any action in the future, let's define the method on the item's data instead.

To do this, we'll define a method named `onSelect` for each item. This method can handle whatever functionality you need. In this case, we'll create a very simple dark and light mode by adding the class `dark` to the body to enable dark mode and remove it to enable light mode.

```javascript
{
  label: "/light",
  onSelect() {
    document.querySelector("body").classList.remove("dark");
    notify("Light Mode enabled");
  }
},
{
  label: "/dark",
  onSelect() {
    document.querySelector("body").classList.add("dark");
    notify("Dark Mode enabled");
  }
},
```

Now, back in the main `onSelect` method, instead of running `console.log(item)`, we can run `item.onSelect()`. This will fire the functions we just created.

We now have functioning actions! 

## Enhancing the omnibar experience

With working actions, we can focus a bit on crafting a strong user experience for our omnibar. 

### Automatic highlight and select

First, let's have Autocomplete automatically highlight the first item in the list. This will allow a user to select an action by just hitting enter.

To add this feature, we need to pass a new prop to the `<Autocomplete />` component. By passing the prop `defaultActiveItemId` a value of `"0"`, we can have the first item in the list be active. Any active item can be selected by hitting enter. This makes for a solid keyboard experience.

### Creating a more robust UI with a new component

Let's abstract the `template` to use a separate component called `Action`. We can build this in a separate file or create it in `App.js`. 

To use the component, we'll pass it a `hit` prop that will contain our item data. This component will also use specific class names that match specific items in the classic theme we imported at the beginning of the tutorial.

Inside the markup, we provide the highlighted text and two new items: `hit.icon` and an SVG representation of the return key. This adds some customized iconography for our actions and an indication to users that they can use the enter key to select an item.

```javascript
function Action({ hit }) {
  // Component to display the items  
  return (
    <div className="aa-ItemWrapper">
      <div className="aa-ItemContent">
        <div className="aa-ItemIcon">{hit.icon}</div>
        <div className="aa-ItemContentBody">
          <div className="aa-ItemContentTitle">
            <span>{hit.highlighted}</span>
          </div>
        </div>
      </div>
      <div className="aa-ItemActions">
        <button
          className="aa-ItemActionButton aa-DesktopOnly aa-ActiveOnly"
          type="button"
          title="Select"
        >
          <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor">
            <path d="M18.984 6.984h2.016v6h-15.188l3.609 3.609-1.406 1.406-6-6 6-6 1.406 1.406-3.609 3.609h13.172v-4.031z" />
          </svg>
        </button>
      </div>
    </div>
  );
}
```

Once the component is created, we need to change our `item` template to use it.

```javascript
templates: {
  item({ item }) {
    return <Action hit={item} />;
  }
}
```

We'll also need to add an icon property to each of our action items. In this example, we have some hand-crafted SVGs, but any icon library will work.

```javascript
return [
  {
    icon: (
      <svg fill="none" viewBox="0 0 24 24" stroke="currentColor">
        <path
          strokeLinecap="round"
          strokeLinejoin="round"
          strokeWidth={2}
          d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"
        />
      </svg>
    ),
    label: "/dark",
    enabled: state.context.dark,
    onSelect({ setContext }) {
      document.querySelector("body").classList.add("dark");
    }
  },
  {
    icon: (
      <svg fill="none" viewBox="0 0 24 24" stroke="currentColor">
        <path
          strokeLinecap="round"
          strokeLinejoin="round"
          strokeWidth={2}
          d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z"
        />
      </svg>
    ),
    label: "/light",
    onSelect() {
      document.querySelector("body").classList.remove("dark");
      notify("Light Mode enabled");
    }
  },
]
```

This is starting to look really nice. It's a bit odd that the site is in light mode, but the light mode option provides no indication of that. Let's add some context for our users.

### Creating an enabled state with `setContext`

Autocomplete gives us access to state. Let's use that to create an `enabled` state and set that state when our actions are fired.

Let's start by adding a new property to each action named `enabled`.

```javascript
{ //...
  label: "/dark",
  enabled: state.context.dark,
  // ...
},
{ //...
  label: "/light",
  enabled: !state.context.dark,
  // ...
  }
```

This property will check the Autocomplete's state object for a context item labeled `dark`. If `dark` is set to `true`, the dark action will have a true `enabled` state, if `false`, light will be true.

To have that context, we need to set the context of the app during our `onSelect` functions. We can pass the `setContext` method into our `onSelect` functions and use that to set `dark` to true or false.

We need to pass the `setContext` method in the options object for our sources method. Start by changing `getSources={({ query })}` to `getSources={({ query, setContext })}`. Then we can use `setContext` in our `onSelect` functions.

```javascript
onSelect({ setContext }) {
  document.querySelector("body").classList.remove("dark");
  setContext({ dark: false });
}
```

Now all that's left is to use the `enabled` boolean value in our component.

```javascript
function Action({ hit }) {
  // Component to display the items
  return (
    <div className="aa-ItemWrapper">
      <div className="aa-ItemContent">
        <div className="aa-ItemIcon">{hit.icon}</div>
        <div className="aa-ItemContentBody">
          <div className="aa-ItemContentTitle">
            <span>{hit.highlighted}</span>
            {hit.enabled && (
              <code className="aa-ItemContentTitleNote">Enabled</code>
            )}
          </div>
        </div>
      </div>
      <div className="aa-ItemActions">
        <button
          className="aa-ItemActionButton aa-DesktopOnly aa-ActiveOnly"
          type="button"
          title="Select"
        >
          <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor">
            <path d="M18.984 6.984h2.016v6h-15.188l3.609 3.609-1.406 1.406-6-6 6-6 1.406 1.406-3.609 3.609h13.172v-4.031z" />
          </svg>
        </button>
      </div>
    </div>
  );
}
```

And with that, our omnibar is stateful. This is a relatively simple example of dark mode. To build it out more, you could add and set the context of the omnibar from the overall state of your application or based on information in a user's localStorage.

## Next steps

In this tutorial, we built out Autocomplete to be more than search, but you can also add regular search functionality with a different source object with its own set of templates. You can also extend the actions to match any potential actions your application has. 

Some ideas:

*   Adding to a todo list or saved list
*   Newsletter sign up
*   User profile updates

We'd love to see what you come up with. Fork [the starter sandbox](https://alg.li/omnibar-starter) (or [this finished one](https://codesandbox.io/s/autocomplete-actions-finished-eh7xw)), create something new, and [share it with us on Twitter](https://twitter.com/algolia) or in the comments below.