PhoneInput

Code

import { Field, FieldLabel, PhoneInput } from "@fadymondy/nasaq/web";import { useState } from "react";export function Contact() {  const [phone, setPhone] = useState("");  return (    <Field>      <FieldLabel>Mobile number</FieldLabel>      <PhoneInput value={phone} onValueChange={setPhone} />    </Field>  );}

Forms · beta

Live examples and controls: PhoneInput in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/phone-input.json

One bordered control for a phone number. The start edge holds a country trigger (flag and calling code) that opens a searchable list of every country, each with its flag, its name in English or Arabic and its calling code. The rest is the digits field, which groups the number the way it is written in that country (50 123 4567) and shows an example number as the placeholder. The component emits a canonical E.164 string such as +966501234567.

Calling codes, grouping and examples come from libphonenumber-js (about 19 KB gzipped). Flags are SVGs from country-flag-icons, drawn by CountryFlag, so they look the same on Windows, where flag emoji do not render.

When to useCopy Anchor Link

• Sign-up, checkout and contact forms that need a number a backend can dial.
• Any place users in the Gulf and Arab world type numbers, since those countries are listed first.

When not to useCopy Anchor Link

• Checking that a number really exists or can receive SMS: that needs a lookup service. isValidE164 only checks the numbering plan.
• A one-time code: use OtpInput.
• A plain text field: use Input.

ImportCopy Anchor Link

import { PhoneInput } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { Field, FieldLabel, PhoneInput } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function Contact() {
  const [phone, setPhone] = useState("");
  return (
    <Field>
      <FieldLabel>Mobile number</FieldLabel>
      <PhoneInput value={phone} onValueChange={setPhone} />
    </Field>
  );
}

Value formatCopy Anchor Link

value is E.164: a plus, the calling code, then the national digits, no spaces (+966501234567). It is "" when no digits are typed. While the digits are empty the selected country is still kept in the component.

• A leading 0 in the digits is a trunk prefix and is dropped: 0501234567 with Saudi Arabia selected gives +966501234567. Italy keeps its leading 0.
• Spaces, dashes and brackets are removed as you type; at most 15 digits in total (E.164 limit).
• Arabic-Indic (٠١٢) and Persian (۰۱۲) digits are read as 0-9.
• The field shows the digits grouped for the country (50 123 4567, 416 555 0123); the caret stays after the digit you typed.
• Typing or pasting a number that starts with + (or a browser autofill) picks the country from the number. Shared codes resolve by number range: +1 416… selects Canada, +1 202… the United States. A bare +1 selects the main country, the United States.
• Passing a value (or defaultValue) selects its country the same way.

AnatomyCopy Anchor Link

PhoneInput                  InputGroup                       data-slot="phone-input"
├─ country trigger          Base UI Combobox.Trigger         data-slot="phone-input-country"
│  └─ popup                 search + list                    data-slot="phone-input-content"
│     ├─ search input       data-slot="phone-input-search"
│     └─ items              CountryFlag, name, +dial
├─ digits input             InputGroupInput (Field control)  dir="ltr" inputMode="tel" autoComplete="tel"
└─ hidden input             only when `name` is set

APICopy Anchor Link

PhoneInputCopy Anchor Link

Data and helpersCopy Anchor Link

ExamplesCopy Anchor Link

Prefilled from the serverCopy Anchor Link

import { PhoneInput } from "@fadymondy/nasaq/web";

export const Saved = () => <PhoneInput defaultValue="+971501234567" aria-label="Phone" />;

Only some countriesCopy Anchor Link

import { PHONE_COUNTRIES, PhoneInput } from "@fadymondy/nasaq/web";

const gcc = PHONE_COUNTRIES.filter((c) => ["SA", "AE", "KW", "QA", "BH", "OM"].includes(c.iso));

export const GulfOnly = () => <PhoneInput countries={gcc} preferred={[]} aria-label="Phone" />;

Arabic and validation in a FieldCopy Anchor Link

import { Field, FieldError, FieldLabel, isValidE164, NasaqProvider, PhoneInput } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function PhoneAr() {
  const [phone, setPhone] = useState("");
  const bad = phone !== "" && !isValidE164(phone);
  return (
    <NasaqProvider locale="ar" target="scope">
      <Field invalid={bad}>
        <FieldLabel>رقم الجوال</FieldLabel>
        <PhoneInput value={phone} onValueChange={setPhone} invalid={bad} />
        <FieldError match>أدخل رقمًا كاملًا.</FieldError>
      </Field>
    </NasaqProvider>
  );
}

AccessibilityCopy Anchor Link

The country trigger is a combobox named "Country: Saudi Arabia +966"; the popup search input is named "Search countries". The digits input is a Field control, so FieldLabel, FieldDescription and FieldError name and describe it. The country list is inside its own Field scope so it does not take the outer label.

• The flag is decorative (aria-hidden); the name and code are always text.
• Caller must localise aria-label and any FieldLabel. Built-in strings and country names come in English and Arabic.

RTL & i18nCopy Anchor Link

• The group mirrors: in Arabic the country trigger sits at the right (start) edge.
• The digits input is always dir="ltr" and start-aligned, and dial codes are isolated with bdi dir="ltr", so +966 never reverses.
• Country names follow the active language (English or Arabic, from Intl.DisplayNames) and search matches both.
• Digits are shown Western (0-9). Arabic-Indic and Persian digits typed or pasted by the user are converted.

Styling & tokensCopy Anchor Link

• The shell is InputGroup: border-input, bg-card, rounded-control, focus ring nq-focus, invalid nq-danger.
• The popup uses bg-popover, border-border, shadow-floating; items use nq-selected on highlight.
• Slots: phone-input, phone-input-country, phone-input-content, phone-input-search.
• Extend with className; never override colours with raw hex.

Do / Don'tCopy Anchor Link

• Do store and send the E.164 value, and format it for display separately.
• Do check the number with isValidE164 before submit, and again on the server.
• Don't put your own +966 in the digits; pick the country or paste the full number.
• Don't rely on the flag alone to tell countries apart.

RelatedCopy Anchor Link

• CountryFlag · InputGroup · Combobox · Field · OtpInput

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-forms-phone-input--docs