The <PhoneInput /> component is built on top of react-phone-number-input, wrapping the library to deliver a more consistent API that aligns with Radix UI conventions.
Important: This component implements a non-standard controlled behavior that differs from typical React patterns. The underlying library maintains its own internal state alongside any external state management, making it a "semi-controlled" component. While it works somewhat reliably, it may not behave as expected if you're used to idiomatic controlled components. See the related issue for technical details.
Understanding Phone Formats
Phone numbers can be represented in different formats depending on the context. Understanding these formats is crucial for using the component effectively.
National Format
National format represents phone numbers in their local, country-specific format. This format is most familiar to users within a specific country. For example:
US: (234) 567-8900
UK: 01234 567890
MY: 012-345 6789
JP: 0123-45-6789
International Format
International format follows the E.164 standard, which provides a consistent way to represent phone numbers globally. This format can be displayed in two variants:
Without Country Code
Shows only the subscriber number without the country calling code prefix, useful when the country is already known through the country select or other context. For example:
US: 234 567 8900
UK: 1234 567890
MY: 12 345 6789
JP: 123 45 6789
With Country Code
Includes the country calling code prefix, a universal representation that works across all countries. For example:
US: +1 234 567 8900
UK: +44 1234 567890
MY: +60 12 345 6789
JP: +81 123 45 6789
Formatting Behavior
The component automatically handles phone number formatting based on whether a country is selected.
When no country is selected, it uses international format with country code by default.
When a country is selected, it uses national format by default.
The formatting behavior can be configured to suit different use cases.
When you know the likely country of your users (such as for a local business signup), you can set a default country while still allowing international numbers. This lets users enter phone numbers in their national format for the default country, while maintaining the flexibility to use international formats for any other country.
In this example, the default country is set to Malaysia, with the initial value forced to display in international format rather than the default national format.
Important: Since react-phone-number-input uses a function-based approach for its inputComponent prop, this differs from Radix UI's asChild composition which expects a JSX element directly.
To ensure stable behavior and prevent focus issues, it's recommended to always wrap your input element or custom component with useMemo to maintain a stable reference. Avoid using components directly as children without useMemo, as this will cause focus issues on each change.