Telephone Number Input improvements (#152)

Author: manni497

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- country labels in search country input for `TelephoneNumberInput` includes also national prefix.
+- Clicking on clear icon in search country input for `TelephoneNumberInput` will automatically open the select menu.
+
+### Added
+
+- `pinnedCountries` property in `TelephoneNumberInput` which allows to pin some countries in the top of the list.
+
 ## [3.12.0] - 2025-11-10
 
 ### Added

cypress/cypress/component/TelephoneNumberInput/TelephoneNumberInput.cy.tsx

@@ -22,7 +22,7 @@ it("correctly set telephone number", () => {
   cy.get("@onSubmitSpy").should("be.calledWith", { [name]: "+41123456789" });
 });
 
-it("correctly change country telephone number", () => {
+it("correctly change country telephone number (searching for country or country prefix)", () => {
   const name = faker.random.alpha(10);
 
   mount(
@@ -42,6 +42,16 @@ it("correctly change country telephone number", () => {
 
   cy.get("input[type=submit]").click();
   cy.get("@onSubmitSpy").should("be.calledWith", { [name]: "+391234567890" });
+
+  cy.get(`.MuiInputAdornment-root`).click();
+  cy.get(`.MuiInputBase-input:not(#${name})`).clear();
+  cy.get(`.MuiInputBase-input:not(#${name})`).type("+234");
+  cy.get(`.MuiAutocomplete-option`).click();
+  cy.get(`#${name}`).clear();
+  cy.get(`#${name}`).type("678901234");
+
+  cy.get("input[type=submit]").click();
+  cy.get("@onSubmitSpy").should("be.calledWith", { [name]: "+234678901234" });
 });
 
 it("recognize telephone number coming from default values (even if specified in different format)", () => {
@@ -59,3 +69,22 @@ it("recognize telephone number coming from default values (even if specified in
   cy.get(`.MuiInputAdornment-root`).contains("+44");
   cy.get(`#${name}`).should("have.value", "123456789");
 });
+
+it("pinning contries works", () => {
+  const name = faker.random.alpha(10);
+
+  mount(
+    <div className="p-4">
+      <Form defaultValues={{ [name]: "+4 4  123456789" }} onSubmit={cy.spy().as("onSubmitSpy")}>
+        <TelephoneNumberInput name={name} useBootstrapStyle label="Phone Number" defaultCountry="CH" pinnedCountries={["GB", "IT"]} />
+        <input type="submit" className="mt-4" />
+      </Form>
+    </div>,
+  );
+
+  cy.get(`.MuiInputAdornment-root`).click();
+  cy.get(`.MuiInputBase-input:not(#${name})`).clear();
+  cy.get(`.MuiAutocomplete-listbox`).children().eq(0).should("contain", "+44");
+  cy.get(`.MuiAutocomplete-listbox`).children().eq(1).should("contain", "+39");
+  cy.get(`.MuiAutocomplete-listbox`).children().eq(2).should("contain", "──");
+});

src/lib/TelephoneNumberInput.tsx

@@ -13,6 +13,7 @@ interface TelephoneNumberInputProps<T extends FieldValues>
   onChange?: (telephoneNumber: string) => void;
   onBlur?: FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
   defaultCountry: RegionCode;
+  pinnedCountries?: RegionCode[];
   placeholder?: string;
   renderAutocompleteField?: (children: ReactNode) => ReactNode;
   locale?: string;

src/lib/components/TelephoneNumberInput/TelephoneNumberAutocomplete.tsx

@@ -0,0 +1,87 @@
+import { Dispatch, SetStateAction, useMemo, useState } from "react";
+import { FieldValues, Path, PathValue } from "react-hook-form";
+import { Country, getCountriesOptions, getCountryFromCountryCode } from "../../helpers/telephoneNumber";
+import { TelephoneNumberInputProps } from "../../TelephoneNumberInput";
+import { LabelValueOption } from "../../types/LabelValueOption";
+import { RegionCode } from "google-libphonenumber";
+import { isNullOrWhitespace } from "@neolution-ch/javascript-utils";
+import Autocomplete from "@mui/material/Autocomplete";
+import { useFormContext } from "../../context/FormContext";
+import { PopupState } from "material-ui-popup-state/hooks";
+import { TextField } from "@mui/material";
+import { textFieldBootstrapStyle } from "src/lib/helpers/mui";
+
+interface TelephoneNumberAutocompleteProps<T extends FieldValues>
+  extends Pick<TelephoneNumberInputProps<T>, "pinnedCountries" | "locale" | "useBootstrapStyle" | "name" | "onChange"> {
+  popupState: PopupState;
+  nationalPhoneNumber: string | undefined;
+  country: Country;
+  setCountry: Dispatch<SetStateAction<Country>>;
+}
+
+const TelephoneNumberAutocomplete = <T extends FieldValues>(props: TelephoneNumberAutocompleteProps<T>) => {
+  const {
+    pinnedCountries = [],
+    locale,
+    useBootstrapStyle,
+    name,
+    onChange: propsOnChange,
+    popupState,
+    nationalPhoneNumber,
+    country,
+    setCountry,
+  } = props;
+
+  const [isOpen, setIsOpen] = useState(false);
+  const countryOptions: LabelValueOption[] = useMemo(() => getCountriesOptions(pinnedCountries, locale), [locale, pinnedCountries]);
+  const { setValue } = useFormContext<T>();
+
+  return (
+    <Autocomplete
+      options={countryOptions}
+      value={countryOptions.find((x) => x.value === country.region) || null}
+      disableClearable={false}
+      open={isOpen}
+      onOpen={() => setIsOpen(true)}
+      onClose={() => setIsOpen(false)}
+      getOptionDisabled={(option) => option.disabled ?? false}
+      renderInput={(params) => <TextField {...params} />}
+      sx={{ ...(useBootstrapStyle && textFieldBootstrapStyle), width: 200 }}
+      onInputChange={(_, _value, reason) => {
+        if (reason === "clear") {
+          setIsOpen(true);
+          return;
+        }
+      }}
+      onChange={(_, value, reason) => {
+        // cannot be cleared
+        if (value === null) {
+          return;
+        }
+
+        if (reason === "clear") {
+          setIsOpen(true);
+          return;
+        }
+
+        const country = getCountryFromCountryCode(value.value as RegionCode);
+        setCountry(country);
+        // the value in the form is probably undefined, therefore do not touch the form value
+        if (isNullOrWhitespace(nationalPhoneNumber)) {
+          // nothing to do, value in the form is not changing
+        } else {
+          const telephoneNumber = `+${country.code}${nationalPhoneNumber || ""}`;
+
+          if (propsOnChange) {
+            propsOnChange(telephoneNumber);
+          }
+
+          setValue(name, telephoneNumber as PathValue<T, Path<T>>);
+        }
+        popupState.close();
+      }}
+    />
+  );
+};
+
+export { TelephoneNumberAutocomplete };

src/lib/components/TelephoneNumberInput/TelephoneNumberInputInternal.tsx

@@ -1,24 +1,17 @@
 import TextField from "@mui/material/TextField";
 import PopupState, { bindPopover } from "material-ui-popup-state";
-import { FieldError, FieldValues, get, Path, PathValue, useController } from "react-hook-form";
+import { FieldError, FieldValues, get, useController } from "react-hook-form";
 import { useMarkOnFocusHandler } from "../../hooks/useMarkOnFocusHandler";
 import { textFieldBootstrapStyle } from "../../helpers/mui";
 import { useFormContext } from "../../context/FormContext";
 import { useEffect, useMemo, useRef, useState } from "react";
 import Popover from "@mui/material/Popover";
 import { TelephoneNumberInputProps } from "../../TelephoneNumberInput";
-import { LabelValueOption } from "../../types/LabelValueOption";
-import { PhoneNumberUtil, RegionCode } from "google-libphonenumber";
-import { getName, langs } from "i18n-iso-countries";
-import {
-  Country,
-  extractCountryCodeFromTelephoneNumber,
-  extractNationalNumberFromTelephoneNumber,
-  getCountryFromCountryCode,
-} from "../../helpers/telephoneNumber";
-import { isNullOrWhitespace } from "@neolution-ch/javascript-utils";
-import Autocomplete from "@mui/material/Autocomplete";
+
+import { Country, extractCountryCodeFromTelephoneNumber, extractNationalNumberFromTelephoneNumber } from "../../helpers/telephoneNumber";
 import { TelephoneNumberInputAdornment } from "./TelephoneNumberInputAdornment";
+import { isNullOrWhitespace } from "@neolution-ch/javascript-utils";
+import { TelephoneNumberAutocomplete } from "./TelephoneNumberAutocomplete";
 
 const TelephoneNumberInputInternal = <T extends FieldValues>(props: TelephoneNumberInputProps<T>) => {
   const {
@@ -37,13 +30,11 @@ const TelephoneNumberInputInternal = <T extends FieldValues>(props: TelephoneNum
     useBootstrapStyle = false,
     hideValidationMessage,
     placeholder,
-    locale,
   } = props;
   const {
     control,
     disabled: formDisabled,
     getFieldState,
-    setValue,
     requiredFields,
     formState: { errors },
     hideValidationMessages,
@@ -70,22 +61,6 @@ const TelephoneNumberInputInternal = <T extends FieldValues>(props: TelephoneNum
   const fieldIsRequired = label && typeof label === "string" && requiredFields.includes(name);
   const finalLabel = useMemo(() => (fieldIsRequired ? `${String(label)} *` : label), [fieldIsRequired, label]);
 
-  const countryOptions: LabelValueOption[] = useMemo(() => {
-    const phoneNumberUtil = new PhoneNumberUtil();
-    const registeredLocales = langs();
-    const internalLocale =
-      registeredLocales.length === 1
-        ? registeredLocales[0]
-        : !isNullOrWhitespace(locale) && registeredLocales.includes(locale as string)
-          ? locale
-          : undefined;
-
-    return phoneNumberUtil.getSupportedRegions().map((region) => ({
-      label: isNullOrWhitespace(internalLocale) ? region : getName(region, internalLocale as string) || region,
-      value: region,
-    }));
-  }, [locale]);
-
   // we need to control the country in the case the value inside the form is undefined
   const [country, setCountry] = useState<Country>(extractCountryCodeFromTelephoneNumber(field.value as string | undefined, defaultCountry));
   const resetCountry = useRef(true);
@@ -160,34 +135,12 @@ const TelephoneNumberInputInternal = <T extends FieldValues>(props: TelephoneNum
             }}
           >
             {renderAutocompleteField(
-              <Autocomplete
-                options={countryOptions}
-                value={countryOptions.find((x) => x.value === country.region) || null}
-                disableClearable={false}
-                renderInput={(params) => <TextField {...params} />}
-                sx={{ ...(useBootstrapStyle && textFieldBootstrapStyle), width: 200 }}
-                onChange={(_, value, reason) => {
-                  // cannot be cleared
-                  if (value === null || reason === "clear") {
-                    return;
-                  }
-
-                  const country = getCountryFromCountryCode(value.value as RegionCode);
-                  setCountry(country);
-                  // the value in the form is probably undefined, therefore do not touch the form value
-                  if (isNullOrWhitespace(nationalPhoneNumber)) {
-                    // nothing to do, value in the form is not changing
-                  } else {
-                    const telephoneNumber = `+${country.code}${nationalPhoneNumber || ""}`;
-
-                    if (propsOnChange) {
-                      propsOnChange(telephoneNumber);
-                    }
-
-                    setValue(name, telephoneNumber as PathValue<T, Path<T>>);
-                  }
-                  popupState.close();
-                }}
+              <TelephoneNumberAutocomplete<T>
+                {...props}
+                popupState={popupState}
+                nationalPhoneNumber={nationalPhoneNumber}
+                country={country}
+                setCountry={setCountry}
               />,
             )}
           </Popover>

src/lib/helpers/telephoneNumber.ts

@@ -1,5 +1,7 @@
 import { isNullOrWhitespace } from "@neolution-ch/javascript-utils";
 import { PhoneNumberUtil, RegionCode, RegionCodeUnknown } from "google-libphonenumber";
+import { getName, langs } from "i18n-iso-countries";
+import { LabelValueOption } from "../types/LabelValueOption";
 
 interface Country {
   region: RegionCode;
@@ -80,4 +82,43 @@ const extractNationalNumberFromTelephoneNumber = (number: string | undefined, co
   }
 };
 
-export { getCountryFromCountryCode, extractNationalNumberFromTelephoneNumber, extractCountryCodeFromTelephoneNumber, Country };
+const getCountriesOptions = (pinnedRegions: RegionCode[], locale?: string): LabelValueOption[] => {
+  const phoneNumberUtil = new PhoneNumberUtil();
+
+  const getLabelValueOption = (region: RegionCode, effectiveLocale?: string): LabelValueOption => {
+    return {
+      label: `${isNullOrWhitespace(effectiveLocale) ? region : getName(region, effectiveLocale as string) || region} (+${phoneNumberUtil.getCountryCodeForRegion(region)})`,
+      value: region,
+    };
+  };
+
+  const registeredLocales = langs();
+  const internalLocale =
+    registeredLocales.length === 1
+      ? registeredLocales[0]
+      : !isNullOrWhitespace(locale) && registeredLocales.includes(locale as string)
+        ? locale
+        : undefined;
+
+  const supportedRegions = phoneNumberUtil.getSupportedRegions().filter((x) => !pinnedRegions.includes(x));
+  let labelValueOptions = [];
+
+  if (pinnedRegions.length > 0) {
+    for (const region of pinnedRegions) {
+      labelValueOptions.push(getLabelValueOption(region, internalLocale));
+    }
+
+    labelValueOptions.push({ label: "────────────", value: "", disabled: true });
+  }
+
+  labelValueOptions = [...labelValueOptions, ...supportedRegions.map((region) => getLabelValueOption(region, internalLocale))];
+  return labelValueOptions;
+};
+
+export {
+  getCountryFromCountryCode,
+  extractNationalNumberFromTelephoneNumber,
+  extractCountryCodeFromTelephoneNumber,
+  getCountriesOptions,
+  Country,
+};