Display config

In mode: 'international', the display option decides whether the calling code is part of the input value and how the leading plus behaves. mode: 'national' has no display option: the value always follows the national convention of defaultRegion. See Modes for the split between the two modes.

The display option

type InternationalDisplayConfig =
  | { callingCodeInInput: true; plusPrefix: 'none' | 'fixed' | 'erasable' }
  | { callingCodeInInput: false };

Omitting display means { callingCodeInInput: true, plusPrefix: 'none' }. callingCodeInInput: false requires a defaultRegion; the options type encodes the requirement, so TypeScript rejects the combination without one.

Calling code in the input

With callingCodeInInput: true, the value is the optional plus, the calling code digits, a space once the calling code is complete, and the national digits in international grouping. plusPrefix selects the plus behavior:

plusPrefix	Initial value	After typing 442079460958
'none'	''	'44 20 7946 0958'
'fixed'	'+'	'+44 20 7946 0958'
'erasable'	'+'	'+44 20 7946 0958'

With a defaultRegion, its calling code seeds the initial value: '1 ' for defaultRegion: 'US' with plusPrefix: 'none', '+44 ' for defaultRegion: 'GB' with plusPrefix: 'fixed'.

'none' never renders a plus, but a pasted leading plus is still understood: pasting '+442079460958' produces '44 20 7946 0958'.

'fixed' renders a permanent plus. Deletions act on digits only: backspace directly after the plus and forward delete on it leave the value unchanged, and deleting a selection that covers the plus removes the selected digits but keeps the plus.

The erasable plus

'erasable' gives the user ownership of the plus. The exact editing semantics:

• Backspace with the caret directly after the visible plus removes the plus and keeps every digit: '+44 20 7946 0958' becomes '44 20 7946 0958' with the caret at position 0.
• Forward delete with the caret at position 0, on the plus, removes it the same way.
• Deleting a selection that starts at position 0 removes the plus together with the selected characters.
• Typing '+' at position 0 restores the plus; the caret lands after it.
• setValue infers visibility from the given string: a leading plus shows it, a non-empty value without one keeps it erased, and an empty string resets to the visible plus. initialValue follows the same inference at creation.
• Plus visibility is part of history: undo and redo restore whatever each entry recorded.

The plus is display only. Shown or erased, the digits are read as a calling code followed by a national number, and getPhoneNumber() returns the same result: '+44 20 7946 0958' and '44 20 7946 0958' both format to '+442079460958'.

Calling code outside the input

display: { callingCodeInInput: false } keeps the calling code out of the value entirely. You render the prefix yourself, typically as a static label or a region picker next to the field, and the controller applies the calling code of defaultRegion to every resolution.

const phoneInput = createPhoneInput({
  mode: 'international',
  input: inputElement,
  defaultRegion: 'GB',
  display: { callingCodeInInput: false },
});

phoneInput.setValue('2079460958');
phoneInput.getState().value; // '20 7946 0958'
phoneInput.getState().region; // 'GB'
phoneInput.getPhoneNumber().formatE164(); // '+442079460958'

The value holds only the national digits in international grouping; getPhoneNumber() restores the calling code.

Within a shared calling code, the region still resolves from the digits: with defaultRegion: 'US', entering 2045550123 formats to '204-555-0123' and reports region 'CA', because area code 204 belongs to Manitoba. Call setRegion to switch the prefix from a picker; see Input and picker sync for the wiring and Programmatic control for the method semantics.

Placeholders by display

state.placeholder matches the shape of the value it stands in for. For a United Kingdom mobile example (placeholderNumberType defaults to 'MOBILE'):

Configuration	Placeholder
mode: 'national', defaultRegion: 'GB'	'07400 123456'
callingCodeInInput: true, plusPrefix: 'none'	'44 7400 123456'
callingCodeInInput: true, plusPrefix: 'fixed' or 'erasable'	'+44 7400 123456'
callingCodeInInput: false	'7400 123456'

For 'erasable' the placeholder keeps the plus even while the plus is erased. The placeholder is exposed in state only, never written to the element; see Placeholders.