Function: FormFieldPhone()

FormFieldPhone<TFieldValues, TName>(__namedParameters): Element

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

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

Type Parameter	Default type
TFieldValues extends FieldValues	FieldValues
TName extends string	FieldPath<TFieldValues>

Parameters

Parameter	Type
__namedParameters	FormFieldPhoneProps<TFieldValues, TName>

Returns

Element

Examples

// Default: dropdown with COMMON_PHONE_COUNTRY_CODES, country code managed internally.
// The submitted value includes the country code prefix (e.g. '+15555555555').
<FormFieldPhone name="phone" label="Phone" />

// Set a custom initial country code; the component manages further changes.
<FormFieldPhone name="phone" label="Phone" defaultCountryCode="+55" />

// Listen for country-code changes without managing state externally.
<FormFieldPhone
  name="phone"
  label="Phone"
  onCountryCodeChange={(code) => console.log('selected', code)}
/>

// 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={[]}
/>

// Store the selected country code as a separate form field.
// Submitted data: { phone: '+15555555555', countryCode: '+1' }
<FormFieldPhone
  name="phone"
  label="Phone"
  countryCodeName="countryCode"
/>