Phone Input
A phone number field with a country picker behind the flag (searchable in Arabic and English, with calling codes), formatting the number as you type. It gives the number in international format (E.164).
Ritla scan of this preview: 40 of 41 checks3 breakpointsScanned Known misread of our own scanner: R023
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add phone-inputAlso works with shadcn:
npx shadcn@latest add @ritla/phone-inputDependencies it brings
@base-ui/react@phosphor-icons/reactlibphonenumber-jsOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { PhoneInput } from "@/components/ui/phone-input";<PhoneInput label="Phone number" defaultCountry="SA" onValueChange={(e164, { valid }) => save(e164, valid)} />Examples
States and country list
A saved number (an international defaultValue picks the country), countries for a short list, error and disabled. Flags are static SVGs in public/flags, installed by @ritla/flags.
API reference
PhoneInput
Also takes <input> props (name, autoComplete…).
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | None | Figma's Label. |
value / defaultValue | string | None | The number in international format (“+966501234567”). |
onValueChange | (e164: string, details: { country, national, valid }) => void | None | On every change. valid means a correct length and prefix for the country. |
country / defaultCountry | CountryCode | "SA" | The selected country (ISO code). |
onCountryChange | (country: CountryCode) => void | None | When a country is picked. |
countries | CountryCode[] | None | Limit the list to these countries. |
flagsBase | string | "/flags" | Where the flag SVGs are served. |
required / helperText / error / disabled | … | None | As on Input Field. |
Usage guidelines
A phone input takes one phone number with its country code. When to use it, and how formatting and checks work.
1. When to use Phone input
For one phone number with its country code: sign up, OTP and contact details.
Do
- Pick the country from the locale.
- Show the expected format as helper text.
Don't
- Ask for the country code in a separate field.
- Block unknown numbers without saying why.
2. Format and checks
The picker shows the flag and the dial code; the field takes the local number.
Do
- Check the number when the field loses focus.
- Allow pasting a full number with +.
Don't
- Force one fixed mask for every country.
3. Arabic and RTL
The picker and the label mirror. The number stays left to right and keeps the + at its start.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| EnterArrowDown | On the flag: opens the country list with its search box. |
| ArrowUpArrowDown | Between countries; Enter picks, Escape closes. |
| Tab | From the flag to the number. |
ARIA
- The flag button is named “Country: Saudi Arabia +966” in the page language; the flag image is decorative.
- The number is
type="tel"withautocomplete="tel-national", tied to the label and helper text.
Do
type="tel"andautocomplete="tel".- Name the picker “Country code”.
Don't
- The flag alone to show the country.
Arabic and RTL notes
Mirrors
- The country list follows the page: Arabic names, right to left, sorted in Arabic order.
Does not mirror
- The whole field row is left to right, as numbers are written: flag on the left, then the number, in Arabic too.
- Calling codes (“+966”) are isolated with
<bdi dir="ltr">in the list.
- Numerals
- Typed Arabic-Indic and Persian digits are stored as Western digits (
0123456789); the number shows in Western digits, as dialed. - Arabic typography
- Country names are
label-14in the page font. Search matches Arabic the way people type it, without hamzas or diacritics: «السعوديه» finds «السعودية». - Mixed-direction text
- Search finds a country by its Arabic or English name, its code or its calling code (“966”).
Do
- Keep +962 left to right inside Arabic.
- Arabic country names in the Arabic picker.
Don't
- Put the dial code after the number in Arabic.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Forced-LTR container, or a bidi override, over Arabic content
- Unisolated bidi hazards: phones, emails, Latin tokens inside Arabic text
- tel/email/url inputs rendered RTL (these must stay LTR)
- Identity fields missing autocomplete tokens