Search by Algolia
Haystack EU 2023: Learnings and reflections from our team
ai

Haystack EU 2023: Learnings and reflections from our team

If you have built search experiences, you know creating a great search experience is a never ending process: the data ...

Paul-Louis Nech

Senior ML Engineer

What is k-means clustering? An introduction
product

What is k-means clustering? An introduction

Just as with a school kid who’s left unsupervised when their teacher steps outside to deal with a distraction ...

Catherine Dee

Search and Discovery writer

Feature Spotlight: Synonyms
product

Feature Spotlight: Synonyms

Back in May 2014, we added support for synonyms inside Algolia. We took our time to really nail the details ...

Jaden Baptista

Technical Writer

Feature Spotlight: Query Rules
product

Feature Spotlight: Query Rules

You’re running an ecommerce site for an electronics retailer, and you’re seeing in your analytics that users keep ...

Jaden Baptista

Technical Writer

An introduction to transformer models in neural networks and machine learning
ai

An introduction to transformer models in neural networks and machine learning

What do OpenAI and DeepMind have in common? Give up? These innovative organizations both utilize technology known as transformer models ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What’s the secret of online merchandise management? Giving store merchandisers the right tools
e-commerce

What’s the secret of online merchandise management? Giving store merchandisers the right tools

As a successful in-store boutique manager in 1994, you might have had your merchandisers adorn your street-facing storefront ...

Catherine Dee

Search and Discovery writer

New features and capabilities in Algolia InstantSearch
engineering

New features and capabilities in Algolia InstantSearch

At Algolia, our business is more than search and discovery, it’s the continuous improvement of site search. If you ...

Haroen Viaene

JavaScript Library Developer

Feature Spotlight: Analytics
product

Feature Spotlight: Analytics

Analytics brings math and data into the otherwise very subjective world of ecommerce. It helps companies quantify how well their ...

Jaden Baptista

Technical Writer

What is clustering?
ai

What is clustering?

Amid all the momentous developments in the generative AI data space, are you a data scientist struggling to make sense ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What is a vector database?
product

What is a vector database?

Fashion ideas for guest aunt informal summer wedding Funny movie to get my bored high-schoolers off their addictive gaming ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

Unlock the power of image-based recommendation with Algolia’s LookingSimilar
engineering

Unlock the power of image-based recommendation with Algolia’s LookingSimilar

Imagine you're visiting an online art gallery and a specific painting catches your eye. You'd like to find ...

Raed Chammam

Senior Software Engineer

Empowering Change: Algolia's Global Giving Days Impact Report
algolia

Empowering Change: Algolia's Global Giving Days Impact Report

At Algolia, our commitment to making a positive impact extends far beyond the digital landscape. We believe in the power ...

Amy Ciba

Senior Manager, People Success

Retail personalization: Give your ecommerce customers the tailored shopping experiences they expect and deserve
e-commerce

Retail personalization: Give your ecommerce customers the tailored shopping experiences they expect and deserve

In today’s post-pandemic-yet-still-super-competitive retail landscape, gaining, keeping, and converting ecommerce customers is no easy ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

Algolia x eTail | A busy few days in Boston
algolia

Algolia x eTail | A busy few days in Boston

There are few atmospheres as unique as that of a conference exhibit hall: the air always filled with an indescribable ...

Marissa Wharton

Marketing Content Manager

What are vectors and how do they apply to machine learning?
ai

What are vectors and how do they apply to machine learning?

To consider the question of what vectors are, it helps to be a mathematician, or at least someone who’s ...

Catherine Dee

Search and Discovery writer

Why imports are important in JS
engineering

Why imports are important in JS

My first foray into programming was writing Python on a Raspberry Pi to flicker some LED lights — it wasn’t ...

Jaden Baptista

Technical Writer

What is ecommerce? The complete guide
e-commerce

What is ecommerce? The complete guide

How well do you know the world of modern ecommerce?  With retail ecommerce sales having exceeded $5.7 trillion worldwide ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

Data is king: The role of data capture and integrity in embracing AI
ai

Data is king: The role of data capture and integrity in embracing AI

In a world of artificial intelligence (AI), data serves as the foundation for machine learning (ML) models to identify trends ...

Alexandra Anghel

Director of AI Engineering

Looking for something?

facebookfacebooklinkedinlinkedintwittertwittermailmail

When is a search bar not a search bar? When it’s an “omnibar” built with Autocomplete!

In her episode of Learn with JasonSarah Dayan 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 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!

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 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.

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.

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.

// 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).

// 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.

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.

<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.

<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().

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.

<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.

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.

<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.

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.

{
  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

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.

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.

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 enabledstate and set that state when our actions are fired.

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

{ //...
  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 enabledstate, 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 onSelectfunctions 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.

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.

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 (or this finished one), create something new, and share it with us on Twitter. Check out related solutions on our open source code exchange platform.

About the author
Bryan Robinson

Senior Developer Relations Specialist

githubtwitter

Recommended Articles

Powered byAlgolia Algolia Recommend

Replicating the Algolia documentation search with Autocomplete
ux

Sarah Dayan
François Chalifour

Sarah Dayan &

François Chalifour

Part 4: Supercharging search for ecommerce solutions with Algolia and MongoDB — Frontend implementation and conclusion
engineering

Soma Osvay

Full Stack Engineer, Starschema

Add Autocomplete search to your Strapi CMS
engineering

Chuck Meyer

Sr. Developer Relations Engineer