@nish1896/rhf-mui-components/misc/phone-input/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 { CustomComponentIds } from "../../types/common.js";
import { FormHelperTextProps, FormLabelProps } from "../../types/mui.js";
import { JSX, ReactNode, Ref } from "react";
import { Control, FieldValues, Path, RegisterOptions } from "react-hook-form";
import { TextFieldProps } from "@mui/material/TextField";
import { CountryIso2, ParsedCountry, UsePhoneInputConfig } from "react-international-phone";
//#region src/misc/phone-input/index.d.ts
type PhoneInputChangeReturnValue = {
  phone: string;
  inputValue: string;
  country: ParsedCountry;
};
/**
 * Structured phone value stored in RHF state.
 * `country` is captured directly from the picker because dial codes like +1
 * are shared across multiple countries and cannot be disambiguated later.
 */
type RHFPhoneInputValue = {
  /** Full E.164-style phone value with dial code, e.g. "+15551234567". */phone: string; /** Selected ISO 3166-1 alpha-2 country code, e.g. "us" or "ca". */
  country: CountryIso2; /** Country calling code without the "+" prefix, e.g. "1". */
  dialCode: string; /** National significant number with the dial code stripped. */
  phoneNo: string;
};
type RHFPhoneInputOnValueChangeProps = {
  /** Structured value stored in the React Hook Form field. */newValue: RHFPhoneInputValue; /** Raw change payload returned by `react-international-phone`. */
  phoneData: PhoneInputChangeReturnValue;
};
type RHFPhoneInputCustomOnChangeProps = RHFPhoneInputOnValueChangeProps & {
  /** React Hook Form field change handler. Call this to update form state. */rhfOnChange: (newValue: RHFPhoneInputValue) => void;
};
type InputTextFieldProps = Omit<TextFieldProps, 'name' | 'value' | 'defaultValue' | 'onChange' | 'error' | 'inputRef' | 'type' | 'FormHelperTextProps' | 'ref'>;
type SearchCountryProps = {
  /**
   * Whether to show the inline country search field inside the country dropdown.
   * @default true
   */
  allowCountrySearch?: boolean;
  /**
   * Props forwarded to the internal MUI `TextField`.
   */
  textFieldProps?: Omit<TextFieldProps, 'value' | 'label'>;
  /**
   * Customize the content of each `MenuItem` in the country search dropdown.
   */
  renderCountryMenuItem?: (country: ParsedCountry) => ReactNode;
  /**
   * Text shown when the country search does not match any available country.
   * @default 'No countries found'
   */
  noCountryFoundText?: string;
};
type PhoneInputProps = Omit<UsePhoneInputConfig, 'value' | 'onChange'>;
type RHFPhoneInputProps<T extends FieldValues> = {
  /**
   * 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>>;
  /**
   * Overrides the default phone input change handling.
   * Receives the normalized phone object and the raw react-international-phone change payload.
   * Call `rhfOnChange` with the `RHFPhoneInputValue` that should be stored; else the form value will not be updated.
   *
   * @param rhfOnChange - React Hook Form field change handler for the structured phone value.
   * @param newValue - Normalized phone value containing `phone`, `country`, `dialCode`, and `phoneNo`.
   * @param phoneData - Raw change payload returned by react-international-phone.
   */
  customOnChange?: ({
    rhfOnChange,
    newValue,
    phoneData
  }: RHFPhoneInputCustomOnChangeProps) => void;
  /**
   * Called after the default phone input handler stores the normalized phone value in React Hook Form.
   *
   * ⚠️ Important:
   * This callback is not called when `customOnChange` is used.
   *
   * @param newValue - Normalized phone value containing `phone`, `country`, `dialCode`, and `phoneNo`.
   * @param phoneData - Raw change payload returned by react-international-phone.
   */
  onValueChange?: ({
    newValue,
    phoneData
  }: RHFPhoneInputOnValueChangeProps) => void;
  /**
   * Options for the inline country search field in the country dropdown.
   */
  searchCountryProps?: SearchCountryProps;
  /**
   * 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;
  /**
   * 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'>;
  /**
   * Configuration passed to `react-international-phone`'s `usePhoneInput` hook.
   */
  phoneInputProps?: PhoneInputProps;
  /**
   * Custom ids for generated field, label, helper text, and error elements.
   */
  customIds?: CustomComponentIds;
} & InputTextFieldProps;
declare const RHFPhoneInput: <T extends FieldValues>(props: RHFPhoneInputProps<T> & {
  ref?: Ref<HTMLInputElement>;
}) => JSX.Element;
//#endregion
export { RHFPhoneInputProps, RHFPhoneInputValue, RHFPhoneInput as default };