Document how to prioritise a likely country without selecting it

[Chris-Larkin]

Integration

Vanilla JavaScript library

Description

Could the documentation include a short recipe for using a contextual country hint to order the country list without making it the initial selection?

The existing API appears to support this already:

const countryHint = /* optional, validated ISO alpha-2 code */;

intlTelInput(input, {
  countryOrder: countryHint ? [countryHint] : null,
});

With initialCountry and initialCountryLookup omitted, the input remains in its empty/globe state. When a valid hint is available, that country appears first and the omitted countries remain alphabetical.

The host application can obtain the hint from an explicit account preference, trusted server/CDN country header, or another source it already has. No additional IP-geolocation request is required.

This is a documentation proposal only; I am not proposing a new option or default behaviour.

Use case

A country hint can be useful without being reliable enough to determine the telephone country automatically. Travellers, VPNs, stale account data, and imperfect geolocation can all make automatic selection incorrect.

Prioritising the likely country is lower-risk: a good hint reduces scrolling or searching, while a bad hint does not change the field's value or prevent the user from finding another country.

The best-practices documentation currently covers known countries through initialCountry and IP lookup through initialCountryLookup. This would document the middle case: suggest, but do not select.

I would be happy to prepare the documentation PR in whichever section the maintainers prefer.

[jackocnr]

Hi Chris, thanks for the write-up. We do have an inline example (of setting countryOrder to an iso2 array) on the Options page, under "countryOrder": https://intl-tel-input.com/docs/options#countryorder - we actually try to avoid code examples like the one you gave, which focus on a particular implementation (yours is for the vanilla JS library, whereas others consume the library using the react/vue components etc, where the code is different).

You mention the Best Practices page - yes I suppose it might be helpful to add a short line at the bottom of the "Set the initial country" section that mentions using countryOrder as a more tentative, soft-touch approach. I would be open to a PR that added this. But let's keep it as short and simple as possible. Thanks.

[Chris-Larkin]

Thanks Jack! I’ve opened #2191 with the one-line Best Practices addition you suggested