v29.1.0

• Vue: export Props type so wrappers can emit declarations (e7038eb7)
• Bundle country name translations for locales missing from browser ICU data (49490f49)

v29.0.5

• Update utils to libphonenumber v9.0.32 (dc8544ae)

v29.0.4

• fix: pin dropdown width when countrySearch enabled and matchDropdownWidth disabled (306b61dc)

v29.0.3

• Fix stale country in changeNumber handler when wrapper input fires first (b6a1834d)

v29.0.2

• Fix changeCountry event firing one keystroke late when typing a dial code (fa92dac4)

v29.0.1

• Update utils to libphonenumber v9.0.31 (14277db3)

v29.0.0

This release is a large naming cleanup. One big theme is moving from "dropdown" to "countrySelector" language in cases where it can be either a dropdown or a fullscreen popup depending on context (while still keeping "dropdown" when it only applies to that context). This impacts options, methods, events, CSS classes, and CSS variables. A handful of other options were also clarified or restructured along the way.

There are no behavioural changes for end users, but almost every integration will need some find-and-replace work. There are also two new public instance methods, a fix that makes dropdownParent (previously: dropdownContainer) reposition on scroll instead of closing, and two focus-related bug fixes.

Breaking changes

Options

Before	After	Notes
geoIpLookup	initialCountryLookup	Also no longer requires initialCountry: "auto" — just set initialCountryLookup on its own. Still ignored if initialCountry is set.
nationalMode + formatOnDisplay	numberDisplayFormat	A single option that takes one of "E164", "INTERNATIONAL" (default), or "NATIONAL". See migration notes below.
hiddenInput	hiddenInputs	Function signature is unchanged.
autoPlaceholder	placeholderNumberPolicy	Values are now uppercase: "POLITE" (default), "AGGRESSIVE", "OFF".
fixDropdownWidth	matchDropdownWidth	Same default (true), same behaviour. Renamed because "fix" sounded like a bugfix.
i18n	uiTranslations	The shape of the object is unchanged.
allowDropdown + useFullscreenPopup	countrySelectorMode	A single option that takes one of"DROPDOWN", "FULLSCREEN", "AUTO" (default), or "OFF". See migration notes below.
dropdownContainer	dropdownParent	Renamed. Also: scrolling an ancestor now repositions the open dropdown instead of closing it, so the previous workarounds for sticky/fixed containers are no longer needed.

numberDisplayFormat migration

Replace nationalMode and formatOnDisplay as follows:

Before	After
(defaults)	numberDisplayFormat: "INTERNATIONAL" (default — no change needed)
nationalMode: true	numberDisplayFormat: "NATIONAL"
formatOnDisplay: false	no direct replacement — closest is numberDisplayFormat: "E164"

countrySelectorMode migration

Before	After
(defaults)	countrySelectorMode: "AUTO" (default — picks "FULLSCREEN" on narrow viewports, "DROPDOWN" otherwise)
allowDropdown: false	countrySelectorMode: "OFF"
useFullscreenPopup: true	countrySelectorMode: "FULLSCREEN"
useFullscreenPopup: false	countrySelectorMode: "DROPDOWN"

Instance methods

Before	After
iti.getSelectedCountryData()	iti.getSelectedCountry()
iti.setCountry(iso2)	iti.setSelectedCountry(iso2)

Static methods

Before	After
intlTelInput.getCountryData()	intlTelInput.getAllCountries()

Utils validation methods

The two utils validators have been renamed to align with the matching instance methods (iti.isValidNumber() / iti.isValidNumberPrecise()). The behaviour of each function is unchanged — only the names have moved.

Behaviour	Before (v28)	After (v29)
Length-based check (more future-proof)	utils.isPossibleNumber	utils.isValidNumber
Precise country/area-code check	utils.isValidNumber	utils.isValidNumberPrecise

The instance methods (iti.isValidNumber() and iti.isValidNumberPrecise()) are unchanged.

utils.getExampleNumber signature

Changed from (iso2, nationalMode, numberType, useE164) to (iso2, numberType, format) — the two booleans are now a single format string ("E164" / "INTERNATIONAL" / "NATIONAL" / "RFC3966").

DOM events

Before	After
open:countrydropdown	open:countryselector
close:countrydropdown	close:countryselector

React / Vue / Angular / Svelte wrapper props & emits

The CountryDropdown part of the name has been renamed to CountrySelector everywhere. The exact name follows each framework's convention:

Framework	Before	After
React (prop)	onOpenCountryDropdown / onCloseCountryDropdown	onOpenCountrySelector / onCloseCountrySelector
Svelte (prop)	onOpenCountryDropdown / onCloseCountryDropdown	onOpenCountrySelector / onCloseCountrySelector
Vue (emit)	openCountryDropdown / closeCountryDropdown	openCountrySelector / closeCountrySelector
Angular (@Output)	openCountryDropdown / closeCountryDropdown	openCountrySelector / closeCountrySelector

CSS classes

If you have custom styling that targets any of these, update the selectors:

Before	After
.iti__dropdown-content	.iti__country-selector
.iti--inline-dropdown	.iti--inline-country-selector
.iti--container	.iti--detached-country-selector
.iti--allow-dropdown	.iti--has-country-selector

CSS variables

Before	After
--iti-dropdown-bg	--iti-country-selector-bg

Locale imports (subpath)

The translations directory has been renamed from i18n/ to locale/. If you import translation files via the npm subpath, update them:

- import { ar } from "intl-tel-input/i18n";
+ import { ar } from "intl-tel-input/locale";

(And remember to pass them via uiTranslations, not i18n.)

---

New

• iti.openCountrySelector() and iti.closeCountrySelector() — new public instance methods for programmatically opening/closing the country selector (e.g. from a custom UI control, or to close it in response to a scroll event the library doesn't otherwise see).
• dropdownParent repositions on scroll instead of closing — previously, scrolling an ancestor of the input would close the open dropdown. It now stays open and tracks the input position.

Fixes

• Don't disturb a focused input when initialCountryLookup resolves late (could previously interrupt typing if the lookup finished after the user had started typing).
• Don't re-format the input value on utils load if the input is already focused (same reason).

v28.1.0

• Fix: re-showing container after a shake causes re-shake. Closes #2169 (b93e4ca3)
• Fix: dropdown keydown no longer intercepts other inputs' arrow keys (eb9320ed)
• i18n: enrich aria labels with country interpolation and phone-number context (9fb8039b)
• i18n: fix translation errors (according to claude opus) (1b2caeff)
• i18n: add new translations (45fe2334)
• i18n: remove redundant logic (5441d9e0)

v28.0.9

• fix: address strict paste review feedback (7c414a5e)
• fix: allow native paste events in strictMode (0b296548)

v28.0.8

• Fix arrow-key over-jump when typing "+" with dropdownAlwaysOpen + separateDialCode (ac77ffea)