Skip to content

Phone Input

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add phone-input

    Also works with shadcn: npx shadcn@latest add @ritla/phone-input

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/reactlibphonenumber-js

  3. Or 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

phone-input.tsx
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.

EnglishMirroredArabic
LTR →

API reference

PhoneInput

Also takes <input> props (name, autoComplete…).

PropTypeDefaultDescription
labelReactNodeNoneFigma's Label.
value / defaultValuestringNoneThe number in international format (“+966501234567”).
onValueChange(e164: string, details: { country, national, valid }) => voidNoneOn every change. valid means a correct length and prefix for the country.
country / defaultCountryCountryCode"SA"The selected country (ISO code).
onCountryChange(country: CountryCode) => voidNoneWhen a country is picked.
countriesCountryCode[]NoneLimit the list to these countries.
flagsBasestring"/flags"Where the flag SVGs are served.
required / helperText / error / disabled…NoneAs 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.

KeyAction
EnterArrowDownOn the flag: opens the country list with its search box.
ArrowUpArrowDownBetween countries; Enter picks, Escape closes.
TabFrom 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" with autocomplete="tel-national", tied to the label and helper text.

Do

  • type="tel" and autocomplete="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-14 in 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.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R020Forced-LTR container, or a bidi override, over Arabic content
  • R021Unisolated bidi hazards: phones, emails, Latin tokens inside Arabic text
  • R070tel/email/url inputs rendered RTL (these must stay LTR)
  • R073Identity fields missing autocomplete tokens