Placeholders

Every PhoneInput state carries placeholder: an example number for the resolved region, formatted to match the exact shape the field would hold. The SDK computes it from real example numbers in the engine metadata and exposes it as data; applying it to the element is yours. It is never written to the placeholder attribute automatically. This guide covers what the value is, how it adapts, and when it is null. It assumes a PhoneInput attached as in getting started.

Reading and applying it

state.placeholder is a string | null. Set it on the element yourself:

function render(): void {
  const { placeholder } = phoneInput.getState();
  if (placeholder === null) inputElement.removeAttribute('placeholder');
  else inputElement.setAttribute('placeholder', placeholder);
}

phoneInput.subscribe(render);
render();

Because the placeholder tracks the resolved region, it can change while the user types: an international field with no default region has no placeholder until the calling code resolves one, then gains one shaped for that region. Subscribing keeps the attribute current; applying it once at construction is enough only when the region is fixed.

A placeholder is an example, not a label. It vanishes on the first typed digit, so keep the field’s label and any hint alongside it; see Accessibility.

It matches the display config

The placeholder is formatted the same way the value would be, so it always stands in for the real input shape. For a United States mobile example, each configuration yields a different string:

Mode and display	state.placeholder
mode: 'national', defaultRegion: 'US'	'(201) 555-0123'
mode: 'international' (default display)	'1 201-555-0123'
callingCodeInInput: true, plusPrefix: 'fixed' or 'erasable'	'+1 201-555-0123'
callingCodeInInput: false	'201-555-0123'

In national mode the placeholder follows the region’s national convention, including the trunk prefix when the region requires one. defaultRegion: 'US', whose prefix is optional, gives '(201) 555-0123'; defaultRegion: 'AE', whose prefix is required, gives '050 123 4567' with the leading 0.

In international mode the calling code and plus follow display, matching the value exactly. With plusPrefix: 'erasable', the placeholder keeps the plus even while the live plus is erased, so it stays a faithful example. See Display config for the display option itself.

It matches the region

The example number always comes from the region in state.region. Switching regions reshapes the placeholder:

phoneInput.getState().placeholder; // '(201) 555-0123' with defaultRegion 'US'
phoneInput.setRegion('GB');
phoneInput.getState().placeholder; // a United Kingdom example, e.g. '07400 123456'

In international mode without a defaultRegion, the region resolves from the digits, so the placeholder appears once the calling code identifies a region and reshapes if further digits move resolution to another region within a shared calling code.

Choosing the example type

The example defaults to a mobile number. Set placeholderNumberType to draw the example from a different number type:

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

phoneInput.getState().placeholder; // '(800) 234-5678'

placeholderNumberType is a NumberType and affects only the placeholder example; it does not constrain what the user may type. To restrict which numbers resolve as valid, use the number-type filter instead; see Filters.

When it is null

state.placeholder is null whenever no example can be produced:

• International mode, no region resolved. With callingCodeInInput: true and no defaultRegion, the placeholder is null until the typed calling code resolves a region. Until then state.region is null and there is nothing to build an example from.
• No example for the region and type. When the metadata has no example number for the resolved region and the requested placeholderNumberType, the placeholder is null.

Handle null by removing the attribute, as the render function above does, rather than writing an empty string.