Skip to main content

Function: FormFieldPhone()

FormFieldPhone<TFieldValues, TName>(__namedParameters): Element

Defined in: packages/forms/src/FormFieldPhone.tsx:196

Generic phone number form field that supports an optional country code prefix.

By default, a country-code dropdown is rendered using COMMON_PHONE_COUNTRY_CODES (15 common countries + a Manual entry; Manual is the first entry at index 0). Pass countryCodeOptions={[]} to disable the dropdown and show a plain phone input.

The format prop defines the pattern for the local phone number (using # as digit placeholders). When a countryCode is provided it is prepended to the format and rendered as a read-only literal inside the input.

When the user selects the "Manual" option (MANUAL_PHONE_COUNTRY_CODE), the pattern mask is disabled and a plain text input is shown so the user can type the full international number freely.

When a country code is provided, the stored value is the country code concatenated directly with the raw local digits (e.g., "+15555555555" for country code "+1" and local digits "5555555555"). When no country code is set, only the raw local digits are stored.

Changing the country code via the dropdown automatically resets the phone number field to an empty string, so a new number can be entered in the correct format for the selected country.

Type Parameters​

TFieldValues​

TFieldValues extends FieldValues = FieldValues

TName​

TName extends string = FieldPath<TFieldValues>

Parameters​

__namedParameters​

FormFieldPhoneProps<TFieldValues, TName>

Returns​

Element

Examples​

// Default: dropdown with COMMON_PHONE_COUNTRY_CODES, US (+1) pre-selected
<FormFieldPhone name="phone" label="Phone" countryCode="+1" />
// Controlled country code — submitted value includes the prefix
// e.g. { phone: '+15555555555' }
const [countryCode, setCountryCode] = React.useState('+1');
<FormFieldPhone
  name="phone"
  label="Phone"
  countryCode={countryCode}
  onCountryCodeChange={setCountryCode}
/>
// No dropdown — plain phone input; value includes the prefix
// e.g. { phone: '+15555555555' }
<FormFieldPhone
  name="phone"
  label="Phone"
  countryCode="+1"
  format="(###) ###-####"
  countryCodeOptions={[]}
/>
// Dynamic format (e.g. Brazilian numbers with 8 or 9 local digits)
<FormFieldPhone
  name="phone"
  label="Phone"
  countryCode="+55"
  format={(value) =>
    value.length > 10 ? '(##) #####-####' : '(##) ####-#####'
  }
  countryCodeOptions={[]}
/>