Mark Ku's Blog
React 元件 · npm

React Intl Phone Number

Drop-in 的國際電話號碼輸入元件 — 一個 <PhoneNumberInput> 就有可搜尋的國旗 / 國碼下拉、E.164 進出、分級驗證與可主題化的現代外觀。

前往 npmGitHub 原始碼
免費 · 開源 (MIT)🧩 TypeScript · antd-free · 輕量
App.tsx
import PhoneNumberInput from 'react-intl-phone-number'
import 'react-intl-phone-number/styles.css'

<PhoneNumberInput
  value={phone}
  onChange={setPhone}
  defaultCountry="TW"
  validationLevel="mobile-strict"
/>
即時互動
+886
912 345 678
+886912345678

主要功能

讓國際電話輸入在 React 裡「開箱即用、開箱即美、開箱即正確」

🌍

可搜尋國家下拉

用國旗或國碼(+886、+66…)快速挑選國家,常用國家置頂、其餘 A→Z 排序,約 245 個地區全支援。

🔢

E.164 進出

value / onChange 一律以 E.164(+886912345678)進出,可直接存資料庫或送後端,免再轉換格式。

分級驗證

strict / mobile-strict / loose 三段等級,手機與市話可分別套用 pattern 或長度檢查,onValidityChange 即時回報有效性。

🎨

可主題化 CSS

每個樣式都是 .ripn-root 上的 CSS 變數,低 specificity 單一 class,Tailwind utility 不用 !important 就能覆寫;也可用 classNames 逐部位指定。

🧩

framework-agnostic

不綁 antd 或任何 UI 框架;核心驗證邏輯(react-intl-phone-number/core)可單獨用於後端或表單,無 React 也能跑。

🌐

內建 i18n

用 messages 物件或自帶的 t(key, vars) 函式覆寫所有文案,可直接重用既有 react-i18next 語系檔。

📞

Google 級號碼規格

解析、格式化與驗證皆由 Google 維護的 google-libphonenumber 提供,定期對齊各國電信主管機關規格——馬來西亞行動門號長度不一、英國 / 加拿大近年為防詐騙重劃號碼區段,都自動跟上,免自己維護 regex。

⌨️

受控、無障礙、會報錯

完全受控元件,支援 onBlur / disabled / inputRef 與 aria-label;失焦後自動顯示驗證錯誤(showError,紅框 + role="alert" + aria-invalid),並提供號碼格式提示 tooltip。

線上試玩

這就是真實安裝在本站的 <PhoneNumberInput> — 直接輸入看看。

驗證等級

Loading…
onChange 輸出(E.164)
(尚未輸入)
驗證狀態
(尚未輸入)
google-libphonenumber 錯誤代碼
—(通過驗證或尚未輸入)

切換驗證等級、輸入不同國家的號碼;欄位失焦後會顯示驗證錯誤訊息(showError),並即時顯示 E.164 輸出、有效狀態與 google-libphonenumber 的原始錯誤代碼。(元件採套件預設淺色主題)

三段驗證等級

依場景決定手機與市話該套用 pattern 還是只查長度。

strict

手機與市話都必須完全符合該國號碼 pattern,最嚴格,適合需要精準的場景。

mobile-strict

手機需 pattern 驗證、市話僅檢查長度。手機要求精準、市話放寬的常見折衷。

loose

手機與市話皆只檢查長度,最寬鬆,適合只要大致合理即可的表單。

快速開始

安裝、引入樣式,丟一個 <PhoneNumberInput> 進去就好。

安裝

必要 peer 依賴

npm i react react-dom google-libphonenumber

react / react-dom 你的專案通常已有;google-libphonenumber 為必要 peer,需另外安裝(號碼解析與驗證由它提供)。

使用方式

import { useState } from 'react'
import PhoneNumberInput from 'react-intl-phone-number'
import 'react-intl-phone-number/styles.css'

export default function App() {
  const [phone, setPhone] = useState('')
  return (
    <PhoneNumberInput
      value={phone}
      onChange={setPhone}
      defaultCountry="TW"
      validationLevel="mobile-strict"
    />
  )
}

常用 Props

全部都有 TypeScript 型別,IDE 自動補全。

valuestring

受控的 E.164 值(如 +886912345678),清空時為空字串。

onChange(value: string) => void

號碼符合 validationLevel 時送出 E.164;未完成時送出部分值,空字串代表國碼後無數字。

validationLevelstrict | mobile-strict | loose

必填。決定何謂「有效」,同時影響 onChange 送出與獨立驗證器。

defaultCountryCountryCode(如 "TW")

初始國家;變更會採用新國家並清空號碼。

onValidityChange(isValid: boolean) => void

當前驗證結果(依 validationLevel)改變時觸發。

showError / errorboolean / ReactNode

showError:失焦後在欄位下方顯示內建驗證錯誤(紅框、role="alert"、aria-invalid);error:自訂覆寫的錯誤訊息(如「必填」)。v0.2.0 新增。

messages / t / classNamesi18n 與樣式覆寫

用 messages 物件或 t() 覆寫文案;classNames 可逐部位(root / select / input / error…)指定 class。

在你的 React App 裡放上正確的國際電話輸入

免費、開源、TypeScript、antd-free。現在就 npm i react-intl-phone-number。

React Intl Phone Number — Drop-in 國際電話號碼輸入元件 | Mark Ku 的技術部落格 - Mark Ku's Blog