Ui Component

@hyperse/hero-tel-input

A polished phone-number input component built with React and Hero UI. Supports international formats, validation, and type inference for seamless integration into form workflows.

reacttypescriptui-componentformhero-uinextjs

Quick start

git clone https://github.com/hyperse-io/hero-tel-input.git

@hyperse/hero-tel-input

A modern, accessible, and feature-rich international telephone input component built with React and HeroUI. Perfect for forms that require phone number input with country selection.

✨ Features

🌍 International Support: Supports all countries with their respective calling codes
🎨 HeroUI Integration: Built on top of HeroUI for consistent design and theming
📱 Smart Formatting: Automatic phone number formatting based on country
🔍 Country Search: Easy country selection with search functionality
🚀 TypeScript: Full TypeScript support with comprehensive type definitions
♿ Accessible: WCAG compliant with proper ARIA attributes
🎯 Form Integration: Works seamlessly with React Hook Form and other form libraries
🔧 Customizable: Extensive customization options for flags, styling, and behavior
📦 Lightweight: Minimal bundle size with tree-shaking support

📦 Installation

npm install @hyperse/hero-tel-input
# or
yarn add @hyperse/hero-tel-input
# or

🚀 Quick Start

📖 Basic Usage

Simple Implementation

With React Hook Form

🎛️ API Reference

Props

Prop	Type	Default	Description
`value`	`string`	`''`	The phone number value
`defaultCountry`	`HeroTelInputCountry`	-	Default country to select
`forceCallingCode`	`boolean`	`false`	Force the calling code to be included
`onlyCountries`	`HeroTelInputCountry[]`	-	Only allow these countries
`excludedCountries`	`HeroTelInputCountry[]`

HeroTelInputInfo

🎨 Advanced Examples

Custom Country Filtering

Force Calling Code

Custom Styling

Form Validation

🌍 Supported Countries

The component supports all countries with their respective calling codes. You can:

Filter by specific countries using onlyCountries
Exclude countries using excludedCountries
Set preferred countries using preferredCountries
Filter by continents using continents

Available Continents

'AF' - Africa
'AS' - Asia
'EU' - Europe
'NA' - North America
'OC' - Oceania
'SA' - South America

Examples

Check out the examples in the examples/ directory:

example-nextjs/ - Next.js integration example
website/ - Documentation website

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

pnpm add @hyperse/hero-tel-input

import { HeroTelInput } from '@hyperse/hero-tel-input';

const [phoneNumber, setPhoneNumber] = useState('');

onChange={(value, info) => {

setPhoneNumber(value);

console.log('Phone info:', info);

placeholder="Enter phone number"

import { HeroTelInput } from '@hyperse/hero-tel-input';

function PhoneInput() {

label="Phone Number"

placeholder="Enter your phone number"

onChange={(value, info) => {

console.log('Value:', value);

console.log('Country:', info.countryCode);

console.log('Calling Code:', info.countryCallingCode);

import { Controller, useForm } from 'react-hook-form';

import { HeroTelInput, matchIsValidTel } from '@hyperse/hero-tel-input';

function PhoneForm() {

const { control, handleSubmit } = useForm();

const onSubmit = (data) => {

console.log('Form data:', data);

validate: (value) => matchIsValidTel(value) || 'Invalid phone number',

render={({ field, fieldState }) => (

label="Phone Number"

isInvalid={fieldState.invalid}

errorMessage={fieldState.error?.message}

<button type="submit">Submit</button>

interface HeroTelInputInfo {

countryCode: HeroTelInputCountry | null; // ISO country code (e.g., 'CN')

countryCallingCode: string | null; // Calling code (e.g., '86')

nationalNumber: string | null; // National number part

numberType: NumberType | null; // Number type (e.g., 'MOBILE')

numberValue: string | null; // E.164 formatted value

reason: 'country' | 'input' | 'blur'; // Change reason

onlyCountries={['US', 'CA', 'MX']}

preferredCountries={['US']}

label="North American Phone"

label="Chinese Phone (with +86)"

base: 'custom-dropdown-base',

trigger: 'custom-trigger',

content: 'custom-content',

import { matchIsValidTel } from '@hyperse/hero-tel-input';

const validatePhone = (value: string) => {

if (!value) return 'Phone number is required';

if (!matchIsValidTel(value)) return 'Invalid phone number';