Components

Telephone Input - Design decisions

Key design decisions for the Telephone Input component.

What is an ADR?

We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

ADR 001 - Country code field and phone field will not interact

Date raised: April 21, 2025
Decision date: April 29, 2025

Context

During a Slack channel discussion, a design and development question was raised about how the country code selector should behave in relation to the phone number input field: Should selecting a country code automatically insert it into the phone number field?

If a user manually enters a country code into the phone number field, should the country code combo box update to reflect it?
The Auth Exp team raised these as feature requests stating that this is what the users expect.
These questions surfaced usability and accessibility concerns, especially regarding user expectations and assistive technology compatibility. Introducing context changes without notifying the user is a violation of WCAG 3.2.2 A.

Decision

The country code selector and the phone number input field will remain visually independent (i.e., they will not automatically insert text or modify each other). This decision avoids introducing complexity that could negatively impact accessibility, particularly for screen reader users and keyboard navigation.

To maintain appropriate validation and user feedback:

A will be leveraged.
This library validates phone numbers in the context of the selected country code, enabling custom validation messages and enforcing correct formatting.

Consequences

Without the validation library, phone number inputs would fall back to a generic validation pattern (e.g., allowing up to 10 or 15 characters). This could result in users submitting phone numbers with invalid formats for the selected country, reducing data quality.
With the validation library, user inputs can be matched against country-specific patterns, improving form accuracy and the user experience while maintaining accessibility standards.

ADR 002 - Geolocation on country code

Decision date: April 21, 2025

Context

The initial idea was to automatically detect and update the user’s country code based on their geolocation to streamline the user experience.

Decision

For the MVP, we won’t implement geolocation-based detection of the user’s country code.

Consequences

Users will need to manually select their country code during the relevant process.

Open questions

Does this go into the component or into the forms library implementation?
Build in a prop for the country code; some of the other libraries were built into a component, it would need to hit another service.
Other teams can use the country code prop and do this outside of the component.

ADR 003 - Usage of flag icon in the country code

Decision date: April 30, 2025

Context

Other platforms, such as Login.gov and ID.me, display a country flag alongside the country code within the combo box dropdown. We explored the option to use a similar approach to enhance the user experience.

Decision

The decision was made to use the country flag.

Consequences

If flags are used, additional work will be required to manage and optimize assets for both design and development environments.
Care must be taken to ensure accessibility compliance (e.g., providing appropriate labels for screen readers).
Potential impact on page load performance if not handled efficiently.

Open questions

Should the flag be treated as an icon or a separate asset?
Where will the flag images be stored (e.g., in Figma, in the codebase, or retrieved via an external asset library)?
What are the performance and accessibility implications?

ADR 004 - Country order and initial country selection

Date proposed: April 29, 2025
Decision date: April 30, 2025

Context

A is available that supports configuration through props to prioritize certain country codes at the top of the dropdown or to default to a specific country.

Decision

The current preference is to default to the United States at the top of the country code dropdown. The majority of mailing addresses are US addresses.

Country Addresses Percentage of addresses

United States 46,536,849 99.86%

Philippines 16,830 0.04%

Germany 11,686 0.03%

Canada 5,366 0.01%

Japan 3,929 0.01%

United Kingdom 3,912 0.01%

Consequences

If a global decision is made, it simplifies implementation and ensures a consistent user experience across applications.
Allowing customization could offer flexibility but may increase complexity in managing variations and support.

Open questions

Should we make a global decision for all implementations (e.g., always default to a specific country like the United States)?
Or should we allow individual teams to customize which countries appear first based on their needs?

ADR 005 - Props allowed for International Phone

Decision date: April 30, 2025

Context

Exploring , we considered multiple prop possibilities.

Prop Include? Notes

allow dropdown No Works the same but without a dropdown, forces users to type country code

Country order No Default order with US at top, alpha order for others

disabled No

exclude countries No Not until we have a use case

fixDropDownWidth No

i18n Maybe Not for MVP

initialCountry No US is the initial country. If added later, validation would be needed to prevent "select country" as an allowed response

initialValue Yes Required for prefill (country code + phone number)

onlyCountries No Not until we have a use case

placeholderNumberType No We don't use placeholders in our fields

separateDialCode No

showFlags Yes Flags shown in all instances

strictMode No We'll allow any character and throw error messages on validation

useFullscreenProp No

Decision

We’ll use these props for MVP:

initialValue (country code + phone number)

Consequences

Teams will be limited in how they can modify the component, but any future modifications will be made available universally through the component.

Props to consider later

i18n
Show/Hide flags

ADR 006 - One field for both international and domestic phone number

Decision date: April 17, 2025

Context

There were discussions about storing international phone numbers in a separate field within the profile. However, due to the current structure of prefill and profile handling, phone numbers are managed as a single field in the API.

Decision

We’ll create a single phone field in the profile that accepts both domestic and international phone numbers for Home, Mobile, and Work contact types.

Consequences

If a form is prefilled with an international phone number but does not support international formats, users may encounter an error upon submission indicating that the phone number must be 10 characters long.
This is a temporary solution for the initial release of the component.
In the future, when a new pattern is established, there may be an opportunity to provide user-facing messaging that clarifies when international phone numbers are not accepted.

ADR 007 - On screens smaller than 360px we will stack the country code and phone number

Decision date: April 29, 2025

Context

On smaller screens it will be difficult to read the full country name in a side-by-side design of the combo box and phone number.

Decision

We’ll stack the components using responsive web design on smaller screens.

Consequences

Mobile and desktop users will be able to easily interact with each field.

ADR 008 - When the combo box is smaller than 216px, country names may be truncated

Decision date: April 29, 2025
Updated: June 3, 2025 to clarify CSS truncation

Context

The longest country name in our list is 33 characters long; the average length is 17 characters. If we design for the outliers, this could negatively affect the design. We will need to truncate country names in certain cases.

Decision

We’ll truncate country names in the combo box selector using CSS. In the dropdown that shows the country names, country names will not be truncated as we will be able to wrap and display country names on two lines.

Consequences

The design of the component will work for a majority of country names, but outliers may be truncated in the collapsed combo box display.
Users will be able to see the full country name when activating the combo box dropdown.
By using CSS for truncation, full country names will be announced for screen reader users. JavaScript truncation doesn’t read the full country name.

Edit this page in GitHub (Permissions required)

Last updated: May 15, 2026