algolia · aymeric-giraudet · Mar 11, 2026 · Mar 9, 2026 · Mar 10, 2026
diff --git a/bundlesize.config.json b/bundlesize.config.json
@@ -14,7 +14,7 @@
     },
     {
       "path": "./packages/instantsearch.js/dist/instantsearch.development.js",
-      "maxSize": "250.75 kB"
+      "maxSize": "251 kB"
     },
     {
       "path": "packages/react-instantsearch-core/dist/umd/ReactInstantSearchCore.min.js",

diff --git a/packages/instantsearch-ui-components/src/components/autocomplete/AutocompleteIndex.tsx b/packages/instantsearch-ui-components/src/components/autocomplete/AutocompleteIndex.tsx
@@ -14,6 +14,7 @@ export type AutocompleteIndexProps<
     onSelect: () => void;
     onApply: () => void;
   }) => JSX.Element;
+  NoResultsComponent?: () => JSX.Element;
   getItemProps: (
     item: T,
     index: number
@@ -41,6 +42,10 @@ export type AutocompleteIndexClassNames = {
    * Class names to apply to each item element
    */
   item: string | string[];
+  /**
+   * Class names to apply to the no results element
+   */
+  noResults: string | string[];
 };
 
 export function createAutocompleteIndexComponent({ createElement }: Renderer) {
@@ -49,11 +54,12 @@ export function createAutocompleteIndexComponent({ createElement }: Renderer) {
       items,
       HeaderComponent,
       ItemComponent,
+      NoResultsComponent,
       getItemProps,
       classNames = {},
     } = userProps;
 
-    if (items.length === 0) {
+    if (items.length === 0 && !NoResultsComponent) {
       return null;
     }
 
@@ -64,31 +70,40 @@ export function createAutocompleteIndexComponent({ createElement }: Renderer) {
             <HeaderComponent items={items} />
           </div>
         )}
-        <ol className={cx('ais-AutocompleteIndexList', classNames.list)}>
-          {items.map((item, index) => {
-            const { className, onSelect, onApply, ...itemProps } = getItemProps(
-              item,
-              index
-            );
-            return (
-              <li
-                key={`${itemProps.id}:${item.objectID}`}
-                {...itemProps}
-                className={cx(
-                  'ais-AutocompleteIndexItem',
-                  classNames.item,
-                  className
-                )}
-              >
-                <ItemComponent
-                  item={item}
-                  onSelect={onSelect}
-                  onApply={onApply}
-                />
-              </li>
-            );
-          })}
-        </ol>
+        {items.length === 0 && NoResultsComponent ? (
+          <div
+            className={cx(
+              'ais-AutocompleteIndexNoResults',
+              classNames.noResults
+            )}
+          >
+            <NoResultsComponent />
+          </div>
+        ) : (
+          <ol className={cx('ais-AutocompleteIndexList', classNames.list)}>
+            {items.map((item, index) => {
+              const { className, onSelect, onApply, ...itemProps } =
+                getItemProps(item, index);
+              return (
+                <li
+                  key={`${itemProps.id}:${item.objectID}`}
+                  {...itemProps}
+                  className={cx(
+                    'ais-AutocompleteIndexItem',
+                    classNames.item,
+                    className
+                  )}
+                >
+                  <ItemComponent
+                    item={item}
+                    onSelect={onSelect}
+                    onApply={onApply}
+                  />
+                </li>
+              );
+            })}
+          </ol>
+        )}
       </div>
     );
   };

diff --git a/.../instantsearch-ui-components/src/components/autocomplete/createAutocompletePropGetters.ts b/.../instantsearch-ui-components/src/components/autocomplete/createAutocompletePropGetters.ts
@@ -74,6 +74,11 @@ export type UsePropGetters<TItem extends BaseHit> = (params: {
    * - Tab key doesn't close panel
    */
   isDetached?: boolean;
+  /**
+   * Whether the panel should be hidden even when open
+   * (e.g., when all sources are empty and there's no custom content to show).
+   */
+  shouldHidePanel?: boolean;
 }) => {
   getInputProps: GetInputProps;
   getItemProps: GetItemProps;
@@ -109,6 +114,7 @@ export function createAutocompletePropGetters({
     onSubmit,
     placeholder,
     isDetached = false,
+    shouldHidePanel = false,
   }: Parameters<UsePropGetters<TItem>>[0]): ReturnType<UsePropGetters<TItem>> {
     const getElementId = createGetElementId(useId());
     const inputRef = useRef<HTMLInputElement>(null);
@@ -281,7 +287,7 @@ export function createAutocompletePropGetters({
         };
       },
       getPanelProps: () => ({
-        hidden: !isOpen,
+        hidden: !isOpen || shouldHidePanel,
         id: getElementId('panel'),
         role: 'grid',
         'aria-labelledby': getElementId('input'),

diff --git a/packages/instantsearch.js/src/widgets/autocomplete/autocomplete.tsx b/packages/instantsearch.js/src/widgets/autocomplete/autocomplete.tsx
@@ -591,6 +591,16 @@ function AutocompleteWrapper<TItem extends BaseHit>({
     query.length > 0 && storage.onAdd(query);
   };
 
+  const allIndicesEmpty = indicesForPanel.every(
+    ({ hits }) => hits.length === 0
+  );
+  const recentEmpty = !storageHits || storageHits.length === 0;
+  const hasNoResultsTemplate = indicesConfig.some(
+    (c) => c.templates?.noResults !== undefined
+  );
+  const shouldHideEmptyPanel =
+    allIndicesEmpty && recentEmpty && !hasNoResultsTemplate && !templates.panel;
+
   const {
     getInputProps,
     getItemProps,
@@ -655,6 +665,7 @@ function AutocompleteWrapper<TItem extends BaseHit>({
     },
     placeholder,
     isDetached,
+    shouldHidePanel: shouldHideEmptyPanel,
   });
 
   // Open panel and focus input when modal opens
@@ -752,6 +763,17 @@ function AutocompleteWrapper<TItem extends BaseHit>({
       );
     };
 
+    const noResultsComponent = currentIndexConfig.templates?.noResults
+      ? () => (
+          <TemplateComponent
+            {...renderState.indexTemplateProps[i]}
+            templateKey="noResults"
+            rootTagName="fragment"
+            data={{}}
+          />
+        )
+      : undefined;
+
     let elementId = indexName;
     if (indexName === showQuerySuggestions?.indexName) {
       elementId = 'suggestions';
@@ -764,6 +786,7 @@ function AutocompleteWrapper<TItem extends BaseHit>({
         key={indexId}
         HeaderComponent={headerComponent}
         ItemComponent={itemComponent}
+        NoResultsComponent={noResultsComponent}
         items={hits.map((item) => ({
           ...item,
           __indexName: indexId,
@@ -894,6 +917,10 @@ type IndexConfig<TItem extends BaseHit> = AutocompleteIndexConfig<TItem> & {
      * Template to use for each result. This template will receive an object containing a single record.
      */
     item: Template<{ item: TItem; onSelect: () => void }>;
+    /**
+     * Template to use when no results are found.
+     */
+    noResults: Template<Record<string, never>>;
   }>;
 
   /**

diff --git a/packages/react-instantsearch/src/widgets/Autocomplete.tsx b/packages/react-instantsearch/src/widgets/Autocomplete.tsx
@@ -124,6 +124,7 @@ type AutocompleteSearchParameters = Omit<PlainSearchParameters, 'index'>;
 type IndexConfig<TItem extends BaseHit> = AutocompleteIndexConfig<TItem> & {
   headerComponent?: AutocompleteIndexProps<TItem>['HeaderComponent'];
   itemComponent: AutocompleteIndexProps<TItem>['ItemComponent'];
+  noResultsComponent?: AutocompleteIndexProps<TItem>['NoResultsComponent'];
   searchParameters?: AutocompleteSearchParameters;
   classNames?: Partial<AutocompleteIndexClassNames>;
 };
@@ -688,6 +689,16 @@ function InnerAutocomplete<TItem extends BaseHit = BaseHit>({
   );
   const hasWarnedMissingPromptSuggestionsChatRef = useRef(false);
 
+  const allIndicesEmpty = indicesForPanel.every(
+    ({ hits }) => hits.length === 0
+  );
+  const recentEmpty = !storageHits || storageHits.length === 0;
+  const hasNoResultsTemplate = indicesConfig.some(
+    (c) => c.noResultsComponent !== undefined
+  );
+  const shouldHideEmptyPanel =
+    allIndicesEmpty && recentEmpty && !hasNoResultsTemplate && !PanelComponent;
+
   const {
     getInputProps,
     getItemProps,
@@ -754,6 +765,7 @@ function InnerAutocomplete<TItem extends BaseHit = BaseHit>({
     },
     placeholder,
     isDetached,
+    shouldHidePanel: shouldHideEmptyPanel,
   });
 
   // Open panel and focus input when modal opens
@@ -830,6 +842,7 @@ function InnerAutocomplete<TItem extends BaseHit = BaseHit>({
         HeaderComponent={currentIndexConfig.headerComponent}
         // @ts-expect-error - there seems to be problems with React.ComponentType and this, but it's actually correct
         ItemComponent={currentIndexConfig.itemComponent}
+        NoResultsComponent={currentIndexConfig.noResultsComponent}
         items={hits.map((item) => ({
           ...item,
           __indexName: indexId,