Search for a command to run...
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.
Phone numbers can be represented in different formats depending on the context. Understanding these formats is crucial for using the component effectively.
National format represents phone numbers in their local, country-specific format. This format is most familiar to users within a specific country. For example:
(234) 567-890001234 567890012-345 67890123-45-6789International 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:
234 567 89001234 56789012 345 6789123 45 6789With Country Code
Includes the country calling code prefix, a universal representation that works across all countries. For example:
+1 234 567 8900+44 1234 567890+60 12 345 6789+81 123 45 6789The component automatically handles phone number formatting based on whether a country is selected.
The formatting behavior can be configured to suit different use cases.
pnpm dlx shadcn@latest add https://ui-x.junwen-k.dev/r/phone-input-primitive.jsonimport * as PhoneInputPrimitive from "@/components/ui/phone-input-primitive";
export default () => (
<PhoneInputPrimitive.Root>
<PhoneInputPrimitive.CountrySelect>
<PhoneInputPrimitive.CountrySelectOption />
</PhoneInputPrimitive.CountrySelect>
<PhoneInputPrimitive.Input />
</PhoneInputPrimitive.Root>
);Basic example with country select and input.
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.
Preferred country has been set to MY (Malaysia).
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.