algolia · aymeric-giraudet · Jul 18, 2025
diff --git a/examples/js/getting-started/src/app.js b/examples/js/getting-started/src/app.js
@@ -18,7 +18,37 @@ const search = instantsearch({
 search.addWidgets([
   autocomplete({
     container: '#searchbox',
-    placeholder: 'Search for products',
+    translations: {
+      placeholder: 'Search for products',
+    },
+    cssClasses: {
+      root: 'aa-Root',
+      input: 'aa-Input',
+      panel: 'aa-Panel',
+      list: 'aa-List',
+      item: 'aa-Item',
+      itemContent: 'aa-ItemContent',
+      itemActionButton: 'aa-ItemActionButton',
+    },
+    templates: {
+      item({ item }, { html }) {
+        return html`<div>${item}</div>`;
+      },
+      panel({ querySuggestions, Item }, { html }) {
+        return html`
+          <div class="aa-PanelLayout">
+            <section class="aa-Source">
+              <ul class="aa-List">
+                ${querySuggestions.map(
+                  (item) =>
+                    html`<li class="aa-Item"><${Item} item=${item} /></li>`
+                )}
+              </ul>
+            </section>
+          </div>
+        `;
+      },
+    },
   }),
 ]);
 

diff --git a/packages/instantsearch-ui-components/src/components/Autocomplete.tsx b/packages/instantsearch-ui-components/src/components/Autocomplete.tsx
@@ -8,6 +8,7 @@ export type AutocompleteProps = {
   isOpen: boolean;
   items: string[];
   placeholder?: string;
+  panelComponent: React.ElementType<any>;
 };
 
 export function createAutocompleteComponent({
@@ -21,6 +22,7 @@ export function createAutocompleteComponent({
       onInput,
       isOpen,
       items,
+      panelComponent: PanelComponent,
     } = userProps;
 
     return (
@@ -64,39 +66,44 @@ export function createAutocompleteComponent({
           </form>
         </div>
         <div className="aa-Panel" hidden={!isOpen}>
-          <div className="aa-PanelLayout">
-            <section className="aa-Source">
-              <ul className="aa-List">
-                {items.map((item) => (
-                  <li key={item} className="aa-Item">
-                    <div className="aa-ItemWrapper">
-                      <div className="aa-ItemContent">
-                        <div className="aa-ItemIcon aa-ItemIcon--noBorder">
-                          <svg viewBox="0 0 24 24" fill="currentColor">
-                            <path d="M16.041 15.856c-0.034 0.026-0.067 0.055-0.099 0.087s-0.060 0.064-0.087 0.099c-1.258 1.213-2.969 1.958-4.855 1.958-1.933 0-3.682-0.782-4.95-2.050s-2.050-3.017-2.050-4.95 0.782-3.682 2.050-4.95 3.017-2.050 4.95-2.050 3.682 0.782 4.95 2.050 2.050 3.017 2.050 4.95c0 1.886-0.745 3.597-1.959 4.856zM21.707 20.293l-3.675-3.675c1.231-1.54 1.968-3.493 1.968-5.618 0-2.485-1.008-4.736-2.636-6.364s-3.879-2.636-6.364-2.636-4.736 1.008-6.364 2.636-2.636 3.879-2.636 6.364 1.008 4.736 2.636 6.364 3.879 2.636 6.364 2.636c2.125 0 4.078-0.737 5.618-1.968l3.675 3.675c0.391 0.391 1.024 0.391 1.414 0s0.391-1.024 0-1.414z"></path>
-                          </svg>
+          {PanelComponent ? (
+            // @ts-ignore
+            <PanelComponent items={items} />
+          ) : (
+            <div className="aa-PanelLayout">
+              <section className="aa-Source">
+                <ul className="aa-List">
+                  {items.map((item) => (
+                    <li key={item} className="aa-Item">
+                      <div className="aa-ItemWrapper">
+                        <div className="aa-ItemContent">
+                          <div className="aa-ItemIcon aa-ItemIcon--noBorder">
+                            <svg viewBox="0 0 24 24" fill="currentColor">
+                              <path d="M16.041 15.856c-0.034 0.026-0.067 0.055-0.099 0.087s-0.060 0.064-0.087 0.099c-1.258 1.213-2.969 1.958-4.855 1.958-1.933 0-3.682-0.782-4.95-2.050s-2.050-3.017-2.050-4.95 0.782-3.682 2.050-4.95 3.017-2.050 4.95-2.050 3.682 0.782 4.95 2.050 2.050 3.017 2.050 4.95c0 1.886-0.745 3.597-1.959 4.856zM21.707 20.293l-3.675-3.675c1.231-1.54 1.968-3.493 1.968-5.618 0-2.485-1.008-4.736-2.636-6.364s-3.879-2.636-6.364-2.636-4.736 1.008-6.364 2.636-2.636 3.879-2.636 6.364 1.008 4.736 2.636 6.364 3.879 2.636 6.364 2.636c2.125 0 4.078-0.737 5.618-1.968l3.675 3.675c0.391 0.391 1.024 0.391 1.414 0s0.391-1.024 0-1.414z"></path>
+                            </svg>
+                          </div>
+                          <div className="aa-ItemContentBody">
+                            <div className="aa-ItemContentTitle">{item}</div>
+                          </div>
                         </div>
-                        <div className="aa-ItemContentBody">
-                          <div className="aa-ItemContentTitle">{item}</div>
+                        <div className="aa-ItemActions">
+                          <button
+                            type="button"
+                            className="aa-ItemActionButton"
+                            title={`Fill query with "${item}"`}
+                          >
+                            <svg viewBox="0 0 24 24" fill="currentColor">
+                              <path d="M8 17v-7.586l8.293 8.293c0.391 0.391 1.024 0.391 1.414 0s0.391-1.024 0-1.414l-8.293-8.293h7.586c0.552 0 1-0.448 1-1s-0.448-1-1-1h-10c-0.552 0-1 0.448-1 1v10c0 0.552 0.448 1 1 1s1-0.448 1-1z"></path>
+                            </svg>
+                          </button>
                         </div>
                       </div>
-                      <div className="aa-ItemActions">
-                        <button
-                          type="button"
-                          className="aa-ItemActionButton"
-                          title={`Fill query with "${item}"`}
-                        >
-                          <svg viewBox="0 0 24 24" fill="currentColor">
-                            <path d="M8 17v-7.586l8.293 8.293c0.391 0.391 1.024 0.391 1.414 0s0.391-1.024 0-1.414l-8.293-8.293h7.586c0.552 0 1-0.448 1-1s-0.448-1-1-1h-10c-0.552 0-1 0.448-1 1v10c0 0.552 0.448 1 1 1s1-0.448 1-1z"></path>
-                          </svg>
-                        </button>
-                      </div>
-                    </div>
-                  </li>
-                ))}
-              </ul>
-            </section>
-          </div>
+                    </li>
+                  ))}
+                </ul>
+              </section>
+            </div>
+          )}
         </div>
       </Fragment>
     );

diff --git a/packages/instantsearch.js/src/widgets/autocomplete/autocomplete.tsx b/packages/instantsearch.js/src/widgets/autocomplete/autocomplete.tsx
@@ -5,6 +5,8 @@
 import { createAutocompleteComponent } from 'instantsearch-ui-components';
 import { Fragment, h, render } from 'preact';
 
+import TemplateComponent from '../../components/Template/Template';
+import { prepareTemplateProps } from '../../lib/templating';
 import { getContainerNode } from '../../lib/utils';
 
 import type { Renderer, WidgetFactory } from '../../types';
@@ -35,18 +37,47 @@ const renderer =
   ({
     placeholder,
     containerNode,
+    templates,
+    renderState,
   }: {
     containerNode: HTMLElement;
     placeholder?: string;
+    templates: { layout: any };
   }): Renderer<AutocompleteRenderState, Partial<AutocompleteWidgetParams>> =>
-  ({ items, isOpen, refine, query }) => {
+  (
+    { items, isOpen, refine, query, instantSearchInstance },
+    isFirstRendering
+  ) => {
+    if (isFirstRendering) {
+      renderState.templateProps = prepareTemplateProps({
+        defaultTemplates: {},
+        templatesConfig: instantSearchInstance.templatesConfig,
+        templates,
+      });
+      return;
+    }
+
+    const panelComponent = (
+      templates.panel
+        ? () => (
+            <TemplateComponent
+              {...renderState.templateProps}
+              templateKey="panel"
+              rootTagName="fragment"
+              data={{ items }}
+            />
+          )
+        : undefined
+    ) as FrequentlyBoughtTogetherUiProps<Hit>['emptyComponent'];
+
     render(
       <Autocomplete
         isOpen={isOpen}
         items={items}
         onInput={(evt) => refine(evt.target.value)}
         query={query}
         placeholder={placeholder}
+        panelComponent={panelComponent}
       />,
       containerNode
     );
@@ -73,13 +104,15 @@ export type AutocompleteWidget = WidgetFactory<
 export default (function autocomplete(
   widgetParams: AutocompleteWidgetParams & AutocompleteConnectorParams
 ) {
-  const { container, placeholder } = widgetParams || {};
+  const { container, placeholder, templates } = widgetParams || {};
 
   const containerNode = getContainerNode(container);
 
   const specializedRenderer = renderer({
     containerNode,
     placeholder,
+    renderState: {},
+    templates,
   });
 
   const makeWidget = connectAutocomplete(specializedRenderer, () =>