v27.0.0 Release Notes

Breaking changes

Components

• Individual option props instead of initOptions. Component options are now passed as individual props rather than nested inside an initOptions object. e.g. <IntlTelInput initOptions={{ initialCountry: "us" }} /> becomes <IntlTelInput initialCountry="us" />.
• Reactive value updates. Components now reactively respond to value updates — see the component docs for details.
• inputProps ignores reserved keys. All components now ignore certain keys in inputProps (e.g. disabled, readonly) — use the dedicated props instead. See the inputProps section of the component docs for the full list.
• React: dropped the initialValue prop — use inputProps.defaultValue instead.
• React: dropped the CJS builds.
• Vue / Svelte: renamed value to initialValue for clarity.
• Vue: switched exported files from .mjs to .js, in line with the other components.
• Svelte: now exports source files instead of a built .mjs file — more idiomatic Svelte.
• Angular: inputProps renamed to inputAttributes.
• Angular: switched to a default export, in line with the other components.
• Angular: removed the PHONE_ERROR_MESSAGES export.

Main plugin

• CJS support dropped. The main intlTelInput.js file now only works in browsers. See the .mjs builds for ESM.
• build/ renamed to dist/. If you're importing files by path (rather than via the aliases in package.json exports), update them — e.g. intl-tel-input/build/js/utils.js → intl-tel-input/dist/js/utils.js.
• Methods that require utils now throw if called too early. Public methods that depend on utils (e.g. getNumber) will throw if called before utils have loaded. Always await iti.promise before using them.
• Country search behaviour: opening the dropdown now highlights and scrolls to the selected country, and the search query is cleared on close.
• onlyCountries and excludeCountries now default to null (previously []), in line with countryOrder.
• API methods that return a country (e.g. getSelectedCountryData) now return null instead of {} when no country is selected.
• intlTelInput.instances is now a Map instead of a plain object.
• Default flag size increased from 12px to 15px tall. You can scale it down again via the --iti-flag-width CSS variable.
• Dropdown arrow: switched from a CSS triangle to a CSS chevron.
• CSS variable renames:
  • --iti-globe-height → --iti-globe-icon-size
  • --iti-search-clear-icon-height → --iti-clear-icon-size
  • --iti-arrow-height / --iti-arrow-width → --iti-arrow-size
  • --iti-triangle-border → --iti-arrow-width

Other notable changes

• Added "type": "module" to package.json.
• Upgraded TypeScript to v6.
• Restructured src/js/i18n — locale directories collapsed into single files.
• Large refactor of component source file structure — no more symlinks.
• Migrated off Grunt (to Node scripts) and Jest (to Vitest).
• Upgraded all dependencies to their latest versions (some were quite old).