feat(autocomplete): add autoHighlight prop

.changeset/angry-pillows-accept.md

@@ -0,0 +1,6 @@
+---
+"@nextui-org/autocomplete": minor
+"@nextui-org/listbox": minor
+---
+
+add prop autoHighlight to enable/disable the automatic focus on autocomplete items (#2186)

apps/docs/content/components/autocomplete/auto-highlight.ts

@@ -0,0 +1,53 @@
+const data = `export const animals = [
+  {label: "Cat", value: "cat", description: "The second most popular pet in the world"},
+  {label: "Dog", value: "dog", description: "The most popular pet in the world"},
+  {label: "Elephant", value: "elephant", description: "The largest land animal"},
+  {label: "Lion", value: "lion", description: "The king of the jungle"},
+  {label: "Tiger", value: "tiger", description: "The largest cat species"},
+  {label: "Giraffe", value: "giraffe", description: "The tallest land animal"},
+  {
+    label: "Dolphin",
+    value: "dolphin",
+    description: "A widely distributed and diverse group of aquatic mammals",
+  },
+  {label: "Penguin", value: "penguin", description: "A group of aquatic flightless birds"},
+  {label: "Zebra", value: "zebra", description: "A several species of African equids"},
+  {
+    label: "Shark",
+    value: "shark",
+    description: "A group of elasmobranch fish characterized by a cartilaginous skeleton",
+  },
+  {
+    label: "Whale",
+    value: "whale",
+    description: "Diverse group of fully aquatic placental marine mammals",
+  },
+  {label: "Otter", value: "otter", description: "A carnivorous mammal in the subfamily Lutrinae"},
+  {label: "Crocodile", value: "crocodile", description: "A large semiaquatic reptile"},
+];`;
+
+const App = `import {Autocomplete, AutocompleteItem} from "@nextui-org/react";
+import {animals} from "./data";
+
+export default function App() {
+  return (
+      <Autocomplete
+        autoHighlight
+        label="Favorite Animal"
+        placeholder="Search an animal"
+        className="max-w-xs"
+        defaultItems={animals}
+      >
+        {(item) => <AutocompleteItem key={item.value}>{item.label}</AutocompleteItem>}
+      </Autocomplete>
+  );
+}`;
+
+const react = {
+  "/App.jsx": App,
+  "/data.js": data,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/components/autocomplete/index.ts

@@ -26,6 +26,7 @@ import customSectionsStyle from "./custom-sections-style";
 import customStyles from "./custom-styles";
 import customEmptyContentMessage from "./custom-empty-content-message";
 import readOnly from "./read-only";
+import autoHighlight from "./auto-highlight";
 
 export const autocompleteContent = {
   usage,
@@ -56,4 +57,5 @@ export const autocompleteContent = {
   customStyles,
   customEmptyContentMessage,
   readOnly,
+  autoHighlight,
 };

apps/docs/content/docs/components/autocomplete.mdx

@@ -84,7 +84,7 @@ the end of the label and the autocomplete will be required.
 
 ### Read Only
 
-If you pass the `isReadOnly` property to the Autocomplete, the Listbox will open to display 
+If you pass the `isReadOnly` property to the Autocomplete, the Listbox will open to display
 all available options, but users won't be able to select any of the listed options.
 
 <CodeDemo title="Read Only" highlightedLines="8" files={autocompleteContent.readOnly} />
@@ -322,6 +322,12 @@ You can use the `AutocompleteSection` component to group autocomplete items.
 
 <CodeDemo title="With Sections" files={autocompleteContent.sections} />
 
+### Auto Highlight
+
+If you pass the `autoHighlight` property to the Autocomplete, the Listbox will show the first list item automatically highlighted.
+
+<CodeDemo title="Auto Highlight" files={autocompleteContent.autoHighlight} />
+
 ### Custom Sections Style
 
 You can customize the sections style by using the `classNames` property of the `AutocompleteSection` component.

packages/components/autocomplete/__tests__/autocomplete.test.tsx

@@ -861,3 +861,75 @@ describe("Autocomplete with React Hook Form", () => {
     expect(onSubmit).toHaveBeenCalledTimes(1);
   });
 });
+
+it("should auto-highlight the first non-disabled item when autoHighlight is true", async () => {
+  const {getByRole, getAllByRole} = render(
+    <Autocomplete
+      autoHighlight
+      aria-label="Favorite Animal"
+      items={itemsData}
+      label="Favorite Animal"
+    >
+      {(item) => <AutocompleteItem key={item.value}>{item.label}</AutocompleteItem>}
+    </Autocomplete>,
+  );
+
+  const input = getByRole("combobox");
+
+  await act(async () => {
+    await userEvent.click(input);
+  });
+
+  const options = getAllByRole("option");
+
+  expect(options[0]).toHaveAttribute("data-hover", "true");
+});
+
+it("should skip disabled items when auto-highlighting", async () => {
+  const {getByRole, getAllByRole} = render(
+    <Autocomplete
+      autoHighlight
+      aria-label="Favorite Animal"
+      disabledKeys={["cat", "dog"]}
+      items={itemsData}
+      label="Favorite Animal"
+    >
+      {(item) => <AutocompleteItem key={item.value}>{item.label}</AutocompleteItem>}
+    </Autocomplete>,
+  );
+
+  const input = getByRole("combobox");
+
+  await act(async () => {
+    await userEvent.click(input);
+  });
+
+  const options = getAllByRole("option");
+
+  expect(options[2]).toHaveAttribute("data-hover", "true");
+});
+
+it("should not auto-highlight when autoHighlight is false", async () => {
+  const {getByRole, getAllByRole} = render(
+    <Autocomplete
+      aria-label="Favorite Animal"
+      autoHighlight={false}
+      items={itemsData}
+      label="Favorite Animal"
+    >
+      {(item) => <AutocompleteItem key={item.value}>{item.label}</AutocompleteItem>}
+    </Autocomplete>,
+  );
+
+  const input = getByRole("combobox");
+
+  await act(async () => {
+    await userEvent.click(input);
+  });
+
+  const options = getAllByRole("option");
+
+  options.forEach((option) => {
+    expect(option).not.toHaveAttribute("data-hover", "true");
+  });
+});

packages/components/autocomplete/src/use-autocomplete.ts

@@ -110,6 +110,11 @@ interface Props<T> extends Omit<HTMLNextUIProps<"input">, keyof ComboBoxProps<T>
    * Callback fired when the select menu is closed.
    */
   onClose?: () => void;
+  /**
+   * Whether to automatically highlight the first item in the list as the user types.
+   * @default false
+   */
+  autoHighlight?: boolean;
 }
 
 export type UseAutocompleteProps<T> = Props<T> &
@@ -165,6 +170,7 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
     onOpenChange,
     onClose,
     isReadOnly = false,
+    autoHighlight = false,
     ...otherProps
   } = props;
 
@@ -319,12 +325,14 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
 
   // focus first non-disabled item
   useEffect(() => {
-    let key = state.collection.getFirstKey();
+    if (autoHighlight) {
+      let key = state.collection.getFirstKey();
 
-    while (key && state.disabledKeys.has(key)) {
-      key = state.collection.getKeyAfter(key);
+      while (key && state.disabledKeys.has(key)) {
+        key = state.collection.getKeyAfter(key);
+      }
+      state.selectionManager.setFocusedKey(key);
     }
-    state.selectionManager.setFocusedKey(key);
   }, [state.collection, state.disabledKeys]);
 
   useEffect(() => {
@@ -432,6 +440,7 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
       ...mergeProps(slotsProps.listboxProps, listBoxProps, {
         shouldHighlightOnFocus: true,
       }),
+      autoHighlight,
     } as ListboxProps);
 
   const getPopoverProps = (props: DOMAttributes = {}) => {
@@ -515,6 +524,7 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
     disableAnimation,
     allowsCustomValue,
     selectorIcon,
+    autoHighlight,
     getBaseProps,
     getInputProps,
     getListBoxProps,

packages/components/autocomplete/stories/autocomplete.stories.tsx

@@ -65,6 +65,11 @@ export default {
         type: "boolean",
       },
     },
+    autoHighlight: {
+      control: {
+        type: "boolean",
+      },
+    },
     validationBehavior: {
       control: {
         type: "select",
@@ -803,6 +808,21 @@ const WithReactHookFormTemplate = (args: AutocompleteProps) => {
   );
 };
 
+const AutoHighlightTemplate = ({color, variant, ...args}: AutocompleteProps<Animal>) => (
+  <Autocomplete
+    autoHighlight
+    className="max-w-xs"
+    color={color}
+    defaultItems={animalsData}
+    label="Favorite Animal"
+    placeholder="Select an animal"
+    variant={variant}
+    {...args}
+  >
+    {(item) => <AutocompleteItem key={item.value}>{item.label}</AutocompleteItem>}
+  </Autocomplete>
+);
+
 export const Default = {
   render: Template,
   args: {
@@ -1061,3 +1081,10 @@ export const FullyControlled = {
     ...defaultProps,
   },
 };
+
+export const WithAutoHighlight = {
+  render: AutoHighlightTemplate,
+  args: {
+    ...defaultProps,
+  },
+};

packages/components/listbox/src/listbox.tsx

@@ -24,6 +24,7 @@ function Listbox<T extends object>(props: Props<T>, ref: ForwardedRef<HTMLUListE
     disableAnimation,
     getEmptyContentProps,
     getListProps,
+    autoHighlight,
   } = useListbox<T>({...props, ref});
 
   const content = (
@@ -51,6 +52,7 @@ function Listbox<T extends object>(props: Props<T>, ref: ForwardedRef<HTMLUListE
           <ListboxItem
             key={item.key}
             {...itemProps}
+            autoHighlighted={autoHighlight && state.selectionManager.focusedKey === item.key}
             classNames={mergeProps(itemClasses, item.props?.classNames)}
             shouldHighlightOnFocus={shouldHighlightOnFocus}
           />

packages/components/listbox/src/use-listbox-item.ts

@@ -21,6 +21,7 @@ import {ListState} from "@react-stately/list";
 interface Props<T extends object> extends ListboxItemBaseProps<T> {
   item: Node<T>;
   state: ListState<T>;
+  autoHighlighted?: boolean;
 }
 
 export type UseListboxItemProps<T extends object> = Props<T> &
@@ -46,6 +47,7 @@ export function useListboxItem<T extends object>(originalProps: UseListboxItemPr
     onPress,
     onClick,
     shouldHighlightOnFocus,
+    autoHighlighted = false,
     hideSelectedIcon = false,
     isReadOnly = false,
     ...otherProps
@@ -111,7 +113,8 @@ export function useListboxItem<T extends object>(originalProps: UseListboxItemPr
 
   const isHighlighted =
     (shouldHighlightOnFocus && isFocused) ||
-    (isMobile ? isHovered || isPressed : isHovered || (isFocused && !isFocusVisible));
+    (isMobile ? isHovered || isPressed : isHovered || (isFocused && !isFocusVisible)) ||
+    autoHighlighted;
 
   const getItemProps: PropGetter = (props = {}) => ({
     ref: domRef,
@@ -178,6 +181,7 @@ export function useListboxItem<T extends object>(originalProps: UseListboxItemPr
     selectedIcon,
     hideSelectedIcon,
     disableAnimation,
+    isHighlighted,
     getItemProps,
     getLabelProps,
     getWrapperProps,

packages/components/listbox/src/use-listbox.ts

@@ -92,6 +92,11 @@ interface Props<T> extends Omit<HTMLNextUIProps<"ul">, "children"> {
    * The menu items classNames.
    */
   itemClasses?: ListboxItemProps["classNames"];
+  /**
+   * Whether to automatically highlight the first item in the list.
+   * @default false
+   */
+  autoHighlight?: boolean;
 }
 
 export type UseListboxProps<T = object> = Props<T> & AriaListBoxOptions<T> & ListboxVariantProps;
@@ -118,6 +123,7 @@ export function useListbox<T extends object>(props: UseListboxProps<T>) {
     hideEmptyContent = false,
     shouldHighlightOnFocus = false,
     classNames,
+    autoHighlight = false,
     ...otherProps
   } = props;
 
@@ -181,6 +187,7 @@ export function useListbox<T extends object>(props: UseListboxProps<T>) {
     disableAnimation,
     className,
     itemClasses,
+    autoHighlight,
     getBaseProps,
     getListProps,
     getEmptyContentProps,