Create a custom renderer in React

The autocomplete-js package includes everything you need to render a search experience and bind it to your framework. Use the autocomplete-core package to build a custom UI that differs from the autocomplete-js output.

You might not need a custom renderer. Building a custom renderer is an advanced pattern that uses the autocomplete-core package to fully control the rendered experience. Don’t use it unless you’ve reached limitations with autocomplete-js and its templating capabilities.

Import the package

Begin by importing createAutocomplete from the core package and getAlgoliaResults from the Algolia preset. The preset function autocomplete-preset-algolia retrieves items from an Algolia index.

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { createAutocomplete } from "@algolia/autocomplete-core";
import { getAlgoliaResults } from "@algolia/autocomplete-preset-algolia";

// ...

Initialize Autocomplete

The Autocomplete entry point is the createAutocomplete function, which returns the methods to create the search experience.

JavaScript

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);

function Autocomplete() {
  // (1) Create a React state.
  const [autocompleteState, setAutocompleteState] = React.useState({});
  const autocomplete = React.useMemo(
    () =>
      createAutocomplete({
        onStateChange({ state }) {
          // (2) Synchronize the Autocomplete state with the React state.
          setAutocompleteState(state);
        },
        getSources() {
          return [
            // (3) Use an Algolia index source.
            {
              sourceId: "products",
              getItemInputValue({ item }) {
                return item.query;
              },
              getItems({ query }) {
                return getAlgoliaResults({
                  searchClient,
                  queries: [
                    {
                      indexName: "instant_search",
                      params: {
                        query,
                        hitsPerPage: 4,
                        highlightPreTag: "<mark>",
                        highlightPostTag: "</mark>",
                      },
                    },
                  ],
                });
              },
              getItemUrl({ item }) {
                return item.url;
              },
            },
          ];
        },
      }),
    [],
  );

  // ...
}

Use a React state for the Autocomplete component to re-render when the Autocomplete state changes.
Listen to all Autocomplete state changes to synchronize them with the React state.
This example uses an Algolia index as a source.

This setup gives you access to all the methods you may want to use in the autocomplete variable in your React components.

Use prop getters

Prop getters are methods that return props to use in your components. These props contain accessibility features, event handlers, and so on. They help create a complete experience without exposing their underlying technical elements. The following snippet shows how to use the getRootProps(), getInputProps(), getPanelProps(), getListProps(), and getItemProps() prop getters in the appropriate elements.

JSX

function Autocomplete() {
  // ...

  return (
    <div className="aa-Autocomplete" {...autocomplete.getRootProps({})}>
      <input className="aa-Input" {...autocomplete.getInputProps({})} />
      <div className="aa-Panel" {...autocomplete.getPanelProps({})}>
        {autocompleteState.isOpen &&
          autocompleteState.collections.map((collection, index) => {
            const { source, items } = collection;

            return (
              <div key={`source-${index}`} className="aa-Source">
                {items.length > 0 && (
                  <ul className="aa-List" {...autocomplete.getListProps()}>
                    {items.map((item) => (
                      <li
                        key={item.objectID}
                        className="aa-Item"
                        {...autocomplete.getItemProps({
                          item,
                          source,
                        })}
                      >
                        {item.name}
                      </li>
                    ))}
                  </ul>
                )}
              </div>
            );
          })}
      </div>
    </div>
  );
}

The preceding code demonstrates that you don’t need to worry about keyboard events, or tracking which item is active. Autocomplete handles this under the hood with its prop getters. At this point, you should already have a usable search box:

Improve input accessibility

To improve the input control, wrap it in a form and apply the form props given by Autocomplete:

JSX

function Autocomplete() {
  // ...
  const inputRef = React.useRef(null);

  return (
    <div className="aa-Autocomplete" {...autocomplete.getRootProps({})}>
      <form
        className="aa-Form"
        {...autocomplete.getFormProps({ inputElement: inputRef.current })}
      >
        <input ref={inputRef} {...autocomplete.getInputProps({})} />
      </form>
      {/* ... */}
    </div>
  );
}

The getFormProps prop getter handles submit and reset events. It also respectively blurs and focuses the input when these events happen. Pass the inputElement when calling getFormProps to use these features. Add a label that represents the input and use the getLabelProps prop getter:

JSX

function Autocomplete() {
  // ...
  const inputRef = React.useRef(null);

  return (
    <div className="aa-Autocomplete" {...autocomplete.getRootProps({})}>
      <form
        className="aa-Form"
        {...autocomplete.getFormProps({ inputElement: inputRef.current })}
      >
        <div className="aa-InputWrapperPrefix">
          <label className="aa-Label" {...autocomplete.getLabelProps({})}>
            Search
          </label>
        </div>
        <div className="aa-InputWrapper">
          <input
            className="aa-Input"
            ref={inputRef}
            {...autocomplete.getInputProps({})}
          />
        </div>
      </form>
      {/* ... */}
    </div>
  );
}

Another good practice for search inputs is to display a reset button. Display it if there’s a query.

JSX

function Autocomplete() {
  // ...

  return (
    <div className="aa-Autocomplete" {...autocomplete.getRootProps({})}>
      <form
        className="aa-Form"
        {...autocomplete.getFormProps({ inputElement: inputRef.current })}
      >
        <div className="aa-InputWrapperPrefix">
          <label className="aa-Label" {...autocomplete.getLabelProps({})}>
            Search
          </label>
        </div>
        <div className="aa-InputWrapper">
          <input
            className="aa-Input"
            ref={inputRef}
            {...autocomplete.getInputProps({})}
          />
        </div>
        <div className="aa-InputWrapperSuffix">
          <button className="aa-ClearButton">ｘ</button>
        </div>
      </form>
      {/* ... */}
    </div>
  );
}

Check network status

Displaying UI hints when the network is unstable helps users understand why results aren’t updating in real-time. Examine the status to determine this:

JSX

function Autocomplete() {
  // ...

  return (
    <div className="aa-Autocomplete" {...autocomplete.getRootProps({})}>
      {/* ... */}

      {autocompleteState.isOpen && (
        <div
          className={[
            "aa-Panel",
            autocompleteState.status === "stalled" && "aa-Panel--stalled",
          ]
            .filter(Boolean)
            .join(" ")}
          {...autocomplete.getPanelProps({})}
        >
          {/* ... */}
        </div>
      )}
      {/* ... */}
    </div>
  );
}

You could, for example, create a .aa-Panel--stalled CSS class that lowers items’ opacity to show that search is temporarily stuck or unavailable.

For more information, see Controlling behavior with state.

Mirror a native mobile experience

Native platforms offer better primitives for mobile search experiences. Autocomplete helps provide these capabilities so that the web mobile experience is closer to the native mobile experience. A common feature in mobile native experiences is to close the virtual keyboard when users start scrolling. By automatically hiding the keyboard, you make it simpler for users to discover search results. The panel closes when users tap outside it. The getEnvironmentProps method returns event handlers that let you create this experience:

JSX

function Autocomplete() {
  // ...

  const inputRef = React.useRef(null);
  const formRef = React.useRef(null);
  const panelRef = React.useRef(null);

  const { getEnvironmentProps } = autocomplete;

  React.useEffect(() => {
    if (!(formRef.current && panelRef.current && inputRef.current)) {
      return;
    }

    const { onTouchStart, onTouchMove, onMouseDown } = getEnvironmentProps({
      formElement: formRef.current,
      panelElement: panelRef.current,
      inputElement: inputRef.current,
    });

    window.addEventListener("touchstart", onTouchStart);
    window.addEventListener("touchmove", onTouchMove);
    window.addEventListener("mousedown", onMouseDown);

    return () => {
      window.removeEventListener("touchstart", onTouchStart);
      window.removeEventListener("touchmove", onTouchMove);
      window.removeEventListener("mousedown", onMouseDown);
    };
  }, [getEnvironmentProps, autocompleteState.isOpen]);

  return (
    <div className="aa-Autocomplete" {...autocomplete.getRootProps({})}>
      <form
        ref={formRef}
        className="aa-Form"
        {...autocomplete.getFormProps({ inputElement: inputRef.current })}
      >
        {/* ... */}
      </form>

      {autocompleteState.isOpen && (
        <div
          ref={panelRef}
          className={[
            "aa-Panel",
            autocompleteState.status === "stalled" && "aa-Panel--stalled",
          ]
            .filter(Boolean)
            .join(" ")}
          {...autocomplete.getPanelProps({})}
        >
          {/* ... */}
        </div>
      )}
    </div>
  );
}

This makes the app feel more familiar to mobile users.

Help and discussion

You now have enough knowledge to build your own experience based on Autocomplete. If you find that some topics weren’t covered, feel free to open an issue.

Autocomplete

​Import the package

​Initialize Autocomplete

​Use prop getters

​Improve input accessibility

​Check network status

​Mirror a native mobile experience

​Help and discussion

Import the package

Initialize Autocomplete

Use prop getters

Improve input accessibility

Check network status

Mirror a native mobile experience

Help and discussion