@nish1896/rhf-mui-components/mui/autocomplete/index.d.ts

A suite of 25+ production-ready react-hook-form components built with material-ui. Fully typed, tree-shakable, and optimized for enterprise-grade forms.

import { AutocompleteNewValue, CustomComponentIds, CustomOnChangeProps, StrObjOption } from "../../types/common.js";
import { AutoCompleteTextFieldProps, FormHelperTextProps, FormLabelProps, MuiChipProps } from "../../types/mui.js";
import { JSX, ReactNode, Ref, SyntheticEvent } from "react";
import { Control, FieldValues, Path, RegisterOptions } from "react-hook-form";
import { AutocompleteChangeDetails, AutocompleteChangeReason, AutocompleteProps, AutocompleteValue } from "@mui/material/Autocomplete";

//#region src/mui/autocomplete/index.d.ts
type OmittedAutocompleteProps<Option extends StrObjOption = StrObjOption, Multiple extends boolean = false, DisableClearable extends boolean = false, FreeSolo extends boolean = false> = Omit<AutocompleteProps<Option, Multiple, DisableClearable, FreeSolo>, 'freeSolo' | 'multiple' | 'fullWidth' | 'renderInput' | 'options' | 'value' | 'defaultValue' | 'onChange' | 'getOptionKey' | 'getOptionLabel' | 'isOptionEqualToValue' | 'blurOnSelect' | 'disableClearable' | 'disableCloseOnSelect' | 'ChipProps' | 'ref'>;
type OnValueChangeProps<Option, Multiple extends boolean, DisableClearable extends boolean, FreeSolo extends boolean> = {
  newValue: AutocompleteNewValue<Multiple, DisableClearable>;
  selectedOption: AutocompleteValue<Option, Multiple, DisableClearable, FreeSolo>;
  event: SyntheticEvent<Element, Event>;
  reason: AutocompleteChangeReason;
  details?: AutocompleteChangeDetails<Option>;
};
type RHFAutocompleteProps<T extends FieldValues, Option extends StrObjOption = StrObjOption, LabelKey extends Extract<keyof Option, string> = Extract<keyof Option, string>, ValueKey extends Extract<keyof Option, string> = Extract<keyof Option, string>, Multiple extends boolean = false, DisableClearable extends boolean = false, FreeSolo extends boolean = false> = {
  /**
   * Name/path of the React Hook Form field this component controls.
   */
  fieldName: Path<T>;
  /**
   * React Hook Form control object returned by `useForm`.
   */
  control: Control<T>;
  /**
   * Validation rules passed to React Hook Form for this field.
   */
  registerOptions?: RegisterOptions<T, Path<T>>;
  /**
   * Options rendered by the field.
   */
  options: Option[];
  /**
   * Object key used to read the display label from each option.
   */
  labelKey?: LabelKey;
  /**
   * Object key used to derive the stored field value when options are an array of objects.
   */
  valueKey?: ValueKey;
  /**
   * When true, allows selecting multiple values.
   */
  multiple?: Multiple;
  /**
   * When true, the selected value cannot be cleared from the input.
   * @default false
   */
  disableClearable?: DisableClearable;
  /**
   * When true, the user may type any value not present in `options`.
   *
   * The typed string is stored in RHF state as-is. `selectedOption` in
   * callbacks reflects `Option | string` for single selection, or
   * `(Option | string)[]` when `multiple` is true.
   */
  freeSolo?: FreeSolo;
  /**
   * Overrides the default autocomplete change handling.
   * Receives the normalized RHF value plus the raw MUI selected option/value for the change.
   * Call `rhfOnChange` with the string, string array, or `null` value that should be stored; else the form value will not be updated.
   *
   * @param rhfOnChange - React Hook Form field change handler for the stored autocomplete value.
   * @param newValue - Selected value(s) stored in the form: `string[]` when `multiple` is true,
   * otherwise `string`. Includes `null` only when clearing is allowed (`disableClearable` is false).
   * @param selectedOption - Raw MUI selected option/value, including free-solo strings when enabled.
   * @param event - Original MUI Autocomplete change event.
   * @param reason - MUI Autocomplete reason for the change.
   * @param details - Additional MUI Autocomplete change details, when available.
   */
  customOnChange?: ({
    rhfOnChange,
    newValue,
    selectedOption,
    event,
    reason,
    details
  }: CustomOnChangeProps<OnValueChangeProps<Option, Multiple, DisableClearable, FreeSolo>, AutocompleteNewValue<Multiple, DisableClearable>>) => void;
  /**
   * Called after the default autocomplete handler stores the normalized value in React Hook Form.
   *
   * ⚠️ Important:
   * This callback is not called when `customOnChange` is used.
   *
   * @param newValue - Selected value(s) stored in the form: `string[]` when `multiple` is true,
   * otherwise `string`. Includes `null` only when clearing is allowed (`disableClearable` is false).
   * @param selectedOption - Raw MUI selected option/value, including free-solo strings when enabled.
   * @param event - Original MUI Autocomplete change event.
   * @param reason - MUI Autocomplete reason for the change.
   * @param details - Additional MUI Autocomplete change details, when available.
   */
  onValueChange?: ({
    newValue,
    selectedOption,
    event,
    reason,
    details
  }: OnValueChangeProps<Option, Multiple, DisableClearable, FreeSolo>) => void;
  /**
   * Label content shown for the field. Defaults to a label generated from `fieldName`.
   */
  label?: ReactNode;
  /**
   * When true, renders the field label above the form field instead of inside or beside it.
   */
  showLabelAboveFormField?: boolean;
  /**
   * Props forwarded to the internal `FormLabel`. The `id` is managed by the component.
   */
  formLabelProps?: Omit<FormLabelProps, 'id'>;
  /**
   * When true, hides the rendered field label while preserving accessible labeling where possible.
   */
  hideLabel?: boolean;
  /**
   * When true, marks the field as required in the UI and accessibility attributes.
   */
  required?: boolean;
  /**
   * Helper text shown below the field when there is no visible validation error.
   */
  helperText?: ReactNode;
  /**
   * @deprecated
   * Field error message is now automatically derived from form state.
   * Passing this prop is no longer necessary and it will be removed in the next major version.
   */
  errorMessage?: ReactNode;
  /**
   * If true, hides the error message text while keeping the field in an error state.
   */
  hideErrorMessage?: boolean;
  /**
   * Props forwarded to the internal `FormHelperText`. The `id` is managed by the component.
   */
  formHelperTextProps?: Omit<FormHelperTextProps, 'id'>;
  /**
   * Props forwarded to the internal MUI `TextField`.
   */
  textFieldProps?: AutoCompleteTextFieldProps;
  /**
   * Props forwarded to chips rendered for selected values.
   */
  ChipProps?: MuiChipProps;
  /**
   * Custom ids for generated field, label, helper text, and error elements.
   */
  customIds?: CustomComponentIds;
} & OmittedAutocompleteProps<Option, Multiple, DisableClearable, FreeSolo>;
declare const RHFAutocomplete: <T extends FieldValues, Option extends StrObjOption = StrObjOption, LabelKey extends Extract<keyof Option, string> = Extract<keyof Option, string>, ValueKey extends Extract<keyof Option, string> = Extract<keyof Option, string>, Multiple extends boolean = false, DisableClearable extends boolean = false, FreeSolo extends boolean = false>(props: RHFAutocompleteProps<T, Option, LabelKey, ValueKey, Multiple, DisableClearable, FreeSolo> & {
  ref?: Ref<HTMLInputElement>;
}) => JSX.Element;
//#endregion
export { RHFAutocompleteProps, RHFAutocomplete as default };