fix(autocomplete): return value instead of label in form submission

.changeset/purple-pillows-beg.md

@@ -0,0 +1,5 @@
+---
+"@nextui-org/autocomplete": minor
+---
+
+return autocomplete value instead of label in form submission (#3353, #3343)

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

@@ -767,6 +767,7 @@ describe("Autocomplete with React Hook Form", () => {
   let submitButton: HTMLButtonElement;
   let wrapper: any;
   let onSubmit: () => void;
+  let getReactHookFormValues: (key: string) => string;
 
   beforeEach(() => {
     const {result} = renderHook(() =>
@@ -783,10 +784,13 @@ describe("Autocomplete with React Hook Form", () => {
       handleSubmit,
       register,
       formState: {errors},
+      getValues,
     } = result.current;
 
     onSubmit = jest.fn();
 
+    getReactHookFormValues = getValues;
+
     wrapper = render(
       <form className="flex w-full max-w-xs flex-col gap-2" onSubmit={handleSubmit(onSubmit)}>
         <Autocomplete
@@ -860,4 +864,26 @@ describe("Autocomplete with React Hook Form", () => {
 
     expect(onSubmit).toHaveBeenCalledTimes(1);
   });
+
+  it("should have correct form values", async () => {
+    const user = userEvent.setup();
+
+    await user.click(autocomplete3);
+
+    expect(autocomplete3).toHaveAttribute("aria-expanded", "true");
+
+    let listboxItems = wrapper.getAllByRole("option");
+
+    await user.click(listboxItems[1]);
+
+    expect(autocomplete3).toHaveValue("Dog");
+
+    await user.click(submitButton);
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+
+    expect(getReactHookFormValues("withDefaultValue")).toEqual("cat");
+    expect(getReactHookFormValues("withoutDefaultValue")).toEqual("");
+    expect(getReactHookFormValues("requiredField")).toEqual("dog");
+  });
 });

packages/components/autocomplete/package.json

@@ -55,6 +55,7 @@
     "@nextui-org/use-safe-layout-effect": "workspace:*",
     "@react-aria/combobox": "3.9.1",
     "@react-aria/focus": "3.17.1",
+    "@react-aria/form": "3.0.5",
     "@react-aria/i18n": "3.11.1",
     "@react-aria/interactions": "3.21.3",
     "@react-aria/utils": "3.24.1",

packages/components/autocomplete/src/autocomplete.tsx

@@ -9,6 +9,7 @@ import {ForwardedRef, ReactElement, Ref} from "react";
 import {AnimatePresence} from "framer-motion";
 
 import {UseAutocompleteProps, useAutocomplete} from "./use-autocomplete";
+import {HiddenInput} from "./hidden-input";
 
 interface Props<T> extends UseAutocompleteProps<T> {}
 
@@ -29,6 +30,7 @@ function Autocomplete<T extends object>(props: Props<T>, ref: ForwardedRef<HTMLI
     getClearButtonProps,
     getListBoxWrapperProps,
     getEndContentWrapperProps,
+    getHiddenInputProps,
   } = useAutocomplete<T>({...props, ref});
 
   const popoverContent = isOpen ? (
@@ -43,6 +45,7 @@ function Autocomplete<T extends object>(props: Props<T>, ref: ForwardedRef<HTMLI
 
   return (
     <Component {...getBaseProps()}>
+      <HiddenInput {...getHiddenInputProps()} />
       <Input
         {...getInputProps()}
         endContent={

packages/components/autocomplete/src/hidden-input.tsx

@@ -0,0 +1,85 @@
+import type {ComboBoxState} from "@react-stately/combobox";
+
+import React, {ReactNode, RefObject} from "react";
+import {useFormReset} from "@react-aria/utils";
+import {useFormValidation} from "@react-aria/form";
+
+import {inputData} from "./use-autocomplete";
+
+export interface AriaHiddenInputProps {
+  /**
+   * Describes the type of autocomplete functionality the input should provide if any.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
+   */
+  autoComplete?: string;
+  /** The text label for the input. */
+  label?: ReactNode;
+  /** HTML form input name. */
+  name?: string;
+  /** Sets the disabled state of the input. */
+  isDisabled?: boolean;
+  /** Whether the input is required. */
+  isRequired?: boolean;
+}
+
+type NativeHTMLInputProps = Omit<
+  React.InputHTMLAttributes<HTMLInputElement>,
+  keyof AriaHiddenInputProps
+>;
+
+type CombinedAriaInputProps = NativeHTMLInputProps & AriaHiddenInputProps;
+
+export interface HiddenInputProps<T> extends CombinedAriaInputProps {
+  /** State for the input. */
+  state: ComboBoxState<T>;
+  /** A ref to the hidden `<input>` element. */
+  hiddenInputRef?: RefObject<HTMLInputElement>;
+  /** A ref to the `<input>` element. */
+  inputRef?: RefObject<HTMLInputElement>;
+}
+
+export function useHiddenInput<T>(props: HiddenInputProps<T>) {
+  const data = inputData.get(props.state) || {};
+
+  const {
+    state,
+    autoComplete,
+    name = data.name,
+    isDisabled = data.isDisabled,
+    hiddenInputRef,
+    inputRef,
+    onChange,
+  } = props;
+
+  const {validationBehavior, isRequired} = data;
+
+  useFormReset(inputRef!, state.selectedKey, state.setSelectedKey);
+  useFormValidation(
+    {
+      validationBehavior,
+      focus: () => inputRef?.current?.focus(),
+    },
+    state,
+    inputRef,
+  );
+
+  return {
+    name,
+    ref: hiddenInputRef,
+    type: "hidden",
+    disabled: isDisabled,
+    required: isRequired,
+    autoComplete,
+    value: state.selectedKey ?? inputRef?.current?.value ?? "",
+    onChange: (e: React.ChangeEvent<HTMLInputElement>) => {
+      state.setSelectedKey(e.target.value);
+      onChange?.(e);
+    },
+  };
+}
+
+export function HiddenInput<T>(props: HiddenInputProps<T>) {
+  const inputProps = useHiddenInput(props);
+
+  return <input {...inputProps} />;
+}

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

@@ -5,9 +5,9 @@ import {mapPropsVariants, useProviderContext} from "@nextui-org/system";
 import {useSafeLayoutEffect} from "@nextui-org/use-safe-layout-effect";
 import {autocomplete} from "@nextui-org/theme";
 import {useFilter} from "@react-aria/i18n";
-import {FilterFn, useComboBoxState} from "@react-stately/combobox";
+import {ComboBoxState, FilterFn, useComboBoxState} from "@react-stately/combobox";
 import {ReactRef, useDOMRef} from "@nextui-org/react-utils";
-import {ReactNode, useEffect, useMemo, useRef} from "react";
+import {ReactNode, useCallback, useEffect, useMemo, useRef} from "react";
 import {ComboBoxProps} from "@react-types/combobox";
 import {PopoverProps} from "@nextui-org/popover";
 import {ListboxProps} from "@nextui-org/listbox";
@@ -110,10 +110,25 @@ interface Props<T> extends Omit<HTMLNextUIProps<"input">, keyof ComboBoxProps<T>
    * Callback fired when the select menu is closed.
    */
   onClose?: () => void;
+  /**
+   * Handler that is called when the selection changes.
+   */
+  onSelectionChange?: (keys: React.Key | null) => void;
+}
+interface InputData {
+  isDisabled?: boolean;
+  isRequired?: boolean;
+  name?: string;
+  validationBehavior?: "aria" | "native";
 }
 
+export const inputData = new WeakMap<ComboBoxState<any>, InputData>();
+
 export type UseAutocompleteProps<T> = Props<T> &
-  Omit<InputProps, "children" | "value" | "isClearable" | "defaultValue" | "classNames"> &
+  Omit<
+    InputProps,
+    "children" | "value" | "isClearable" | "defaultValue" | "classNames" | "onSelectionChange"
+  > &
   ComboBoxProps<T> &
   AsyncLoadable &
   AutocompleteVariantProps;
@@ -163,14 +178,25 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
     classNames,
     errorMessage,
     onOpenChange,
+    onChange,
     onClose,
+    onSelectionChange,
     isReadOnly = false,
     ...otherProps
   } = props;
 
   // Setup filter function and state.
   const {contains} = useFilter(filterOptions);
 
+  // Setup refs and get props for child elements.
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const inputWrapperRef = useRef<HTMLDivElement>(null);
+  const listBoxRef = useRef<HTMLUListElement>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const hiddenInputRef = useDOMRef<HTMLInputElement>(ref);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const scrollShadowRef = useDOMRef<HTMLElement>(scrollRefProp);
+
   let state = useComboBoxState({
     ...originalProps,
     children,
@@ -185,6 +211,17 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
         onClose?.();
       }
     },
+    onSelectionChange: (keys) => {
+      onSelectionChange?.(keys);
+      if (onChange && typeof onChange === "function") {
+        onChange({
+          target: {
+            name: hiddenInputRef?.current?.name,
+            value: keys,
+          },
+        } as React.ChangeEvent<HTMLInputElement>);
+      }
+    },
   });
 
   state = {
@@ -194,14 +231,6 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
     }),
   };
 
-  // Setup refs and get props for child elements.
-  const buttonRef = useRef<HTMLButtonElement>(null);
-  const inputWrapperRef = useRef<HTMLDivElement>(null);
-  const listBoxRef = useRef<HTMLUListElement>(null);
-  const popoverRef = useRef<HTMLDivElement>(null);
-  const inputRef = useDOMRef<HTMLInputElement>(ref);
-  const scrollShadowRef = useDOMRef<HTMLElement>(scrollRefProp);
-
   const {
     buttonProps,
     inputProps,
@@ -306,16 +335,21 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
   // i.e. setting ref.current.value to something which is uncontrolled
   // hence, sync the state with `ref.current.value`
   useSafeLayoutEffect(() => {
-    if (!inputRef.current) return;
+    if (!hiddenInputRef.current) return;
 
-    const key = inputRef.current.value;
+    const key = hiddenInputRef.current.value;
     const item = state.collection.getItem(key);
 
     if (item && state.inputValue !== item.textValue) {
       state.setSelectedKey(key);
       state.setInputValue(item.textValue);
     }
-  }, [inputRef.current]);
+
+    if (inputRef?.current) {
+      // sync the value from ref to inputRef for initial display
+      inputRef.current.value = hiddenInputRef.current.value;
+    }
+  }, [hiddenInputRef.current]);
 
   // focus first non-disabled item
   useEffect(() => {
@@ -340,6 +374,17 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
     }
   }, [isOpen]);
 
+  useEffect(() => {
+    if (allowsCustomValue) {
+      onChange?.({
+        target: {
+          name: hiddenInputRef?.current?.name,
+          value: hiddenInputRef?.current?.value,
+        },
+      } as React.ChangeEvent<HTMLInputElement>);
+    }
+  }, [state, allowsCustomValue, inputRef?.current?.value, hiddenInputRef?.current?.value]);
+
   // to prevent the error message:
   // stopPropagation is now the default behavior for events in React Spectrum.
   // You can use continuePropagation() to revert this behavior.
@@ -411,19 +456,24 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
       }),
     } as ButtonProps);
 
-  const getInputProps = () =>
-    ({
-      ...otherProps,
-      ...inputProps,
-      ...slotsProps.inputProps,
+  const getInputProps = () => {
+    const props = mergeProps(otherProps, inputProps, slotsProps.inputProps);
+
+    // `name` will be in the hidden input
+    // so that users can get the value of the input instead of label in form
+    delete props["name"];
+
+    return {
+      ...props,
       isInvalid,
       validationBehavior,
       errorMessage:
         typeof errorMessage === "function"
           ? errorMessage({isInvalid, validationErrors, validationDetails})
           : errorMessage || validationErrors?.join(" "),
       onClick: chain(slotsProps.inputProps.onClick, otherProps.onClick),
-    } as unknown as InputProps);
+    } as InputProps;
+  };
 
   const getListBoxProps = () =>
     ({
@@ -500,6 +550,38 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
     }),
   });
 
+  const getHiddenInputProps = useCallback(
+    (props = {}) => ({
+      state,
+      inputRef,
+      hiddenInputRef,
+      name: originalProps?.name,
+      isRequired: originalProps?.isRequired,
+      autoComplete: originalProps?.autoComplete,
+      isDisabled: originalProps?.isDisabled,
+      onChange,
+      ...props,
+    }),
+    [
+      state,
+      originalProps?.name,
+      originalProps?.autoComplete,
+      originalProps?.isDisabled,
+      originalProps?.isRequired,
+      inputRef,
+      hiddenInputRef,
+    ],
+  );
+
+  // store the data to be used in useHiddenInput
+  inputData.set(state, {
+    isDisabled: originalProps?.isDisabled,
+    isRequired: originalProps?.isRequired,
+    name: originalProps?.name,
+    // TODO: Future enhancement to support "aria" validation behavior.
+    validationBehavior: "native",
+  });
+
   return {
     Component,
     inputRef,
@@ -524,6 +606,7 @@ export function useAutocomplete<T extends object>(originalProps: UseAutocomplete
     getSelectorButtonProps,
     getListBoxWrapperProps,
     getEndContentWrapperProps,
+    getHiddenInputProps,
   };
 }