Skip to content
Telixon

Modes

createPhoneInput takes a mode that decides two things: what the input value shows, and how the region is resolved from the digits. The two modes map one-to-one onto the core input controllers described in Input controller.

mode Value shows Region resolved from defaultRegion
'national' The national number in defaultRegion’s convention Fixed to defaultRegion Required
'international' Calling code and national number in one value (default) The digits, across all 245 regions Optional

National mode

Section titled “National mode”

mode: 'national' formats the value in the national convention of a single region and reads every number as belonging to it. defaultRegion is required; it is the only region the input ever resolves to.

const phoneInput = createPhoneInput({
  mode: 'national',
  input,
  defaultRegion: 'US',
});

Typing 2015550123 produces (201) 555-0123, and getPhoneNumber().getRegion() is 'US'. In a region whose national prefix is written, the prefix stays in the value: with defaultRegion: 'GB', typing 07400123456 produces 07400 123456 while getPhoneNumber().formatE164() returns '+447400123456'. The value follows the region’s own convention; there is no calling code and no plus in the field.

National mode has no display option: the value always follows defaultRegion. To show or hide a calling code, or to render a leading plus, use international mode.

International mode

Section titled “International mode”

mode: 'international' resolves the region from the digits themselves. Every calling code across the 245 regions is reachable in one field, and the region can change as the user types.

const phoneInput = createPhoneInput({
  mode: 'international',
  input,
});

Typing 442079460958 produces 44 20 7946 0958, and getPhoneNumber().getRegion() is 'GB', resolved from the 44 calling code. The display option controls how the calling code appears in the value; it is covered in full in Display config.

Choosing a mode

Section titled “Choosing a mode”

The question is whether the region is known before the user types.

  • A checkout or address form scoped to one country knows the region. mode: 'national' with that defaultRegion shows the local convention the user expects and never resolves to another region.
  • A global signup does not know the region. mode: 'international' lets the user enter any calling code, and the region resolves from what they type.

International mode also covers the case where the region is known but you still want a calling code in play: pair it with display: { callingCodeInInput: false } and a defaultRegion, and render the prefix yourself next to a national-shaped field.

defaultRegion in each mode

Section titled “defaultRegion in each mode”

defaultRegion means something different in the two modes.

  • In national mode it is required and fixed: it selects the formatting convention and is the region every number resolves to.
  • In international mode it is optional. It seeds the initial value with the region’s calling code and acts as the fallback for input that carries no calling code of its own. The region still resolves from the digits, so a defaultRegion: 'US' international input reports region 'CA' for a Canadian area code.

display: { callingCodeInInput: false } is the one case where international mode requires defaultRegion: with the calling code outside the value, the controller needs a region to apply. The options type encodes that requirement, so TypeScript rejects the combination without one.

Display config interactions

Section titled “Display config interactions”

The display option belongs to international mode only.

  • National mode: passing display is a type error. The value is always the national convention of defaultRegion.
  • International mode, display omitted: the calling code is part of the value with no leading plus.
  • International mode, display: { callingCodeInInput: true, plusPrefix }: the calling code stays in the value; plusPrefix is 'none', 'fixed', or 'erasable'.
  • International mode, display: { callingCodeInInput: false }: the calling code leaves the value and defaultRegion is required.

The placeholder in state follows the same split. In national mode it is a national example ('07400 123456' for 'GB'); in international mode it takes the shape the display config produces. The mapping is tabulated in Display config.

Next steps

Section titled “Next steps”