ngxsmk-tel-input

An Angular telephone input component with country dropdown, flags, and robust validation/formatting. Wraps intl-tel-input for the UI and libphonenumber-js for parsing/validation. Implements ControlValueAccessor so it plugs into Angular Forms.

Emits E.164 by default (e.g. +14155550123). SSR‑safe via lazy browser‑only import.

Try it live on StackBlitz

Features

Country dropdown with flags
E.164 output (display can be configured via nationalDisplay)
Reactive & template‑driven Forms support (CVA)
Built‑in validation using libphonenumber‑js
Enhanced validation: Detects invalid country codes (like "11", "99") and shows appropriate error states
Mobile responsive: Optimized for touch devices with proper tap targets, prevents iOS zoom, and responsive dropdown
Dark & Light themes: Comprehensive theme system with automatic system preference detection
Accessibility: Full ARIA support, screen reader compatibility, keyboard navigation
Parent fieldset disabled detection: Natively reacts to parent <fieldset> disabled state changes (via DoCheck hook), disabling dropdown and matching application styles.
Integrations & Ionic ready: Built-in support for Twilio, Vonage, AWS SNS, and Ionic Framework overlays/themes (see INTEGRATIONS.md)
SSR‑friendly (no window on the server)
Easy theming via CSS variables
Nice UX options: label/hint/error text, sizes, variants, clear button, autofocus, select-on-focus
Masking & caret-friendly as-you-type formatting (optional)
Format only when valid (formatWhenValid) and lock once valid (lockWhenValid) to prevent extra digits

Requirements

Angular 17+ (actively tested on Angular 19 - 22)
Node 18 or 20

Library peerDependencies target Angular >=17.

Zone.js Compatibility

This component works seamlessly with both Zone.js and zoneless Angular:

With Zone.js (traditional Angular): Full compatibility
Without Zone.js (Angular 18+ zoneless): Full compatibility
All data binding types: Property bindings, event bindings, two-way bindings
Reactive Forms & Template-driven Forms: Full support
Signals: Compatible with Angular signals (Angular 16+)

The component automatically detects whether Zone.js is available and adapts its change detection strategy accordingly.

Install

npm i ngxsmk-tel-input intl-tel-input libphonenumber-js

Add styles & flag assets (in your app, not the library)

Update your app’s angular.json:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "node_modules/intl-tel-input/build/css/intlTelInput.css"
            ],
            "assets": [
              { "glob": "**/*", "input": "node_modules/intl-tel-input/build/img", "output": "assets/intl-tel-input/img" }
            ]
          }
        }
      }
    }
  }
}

Optional override to ensure flags resolve (e.g., Vite/Angular 17+): add to your global styles

.iti__flag { background-image: url("/assets/intl-tel-input/img/flags.png"); }
@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
  .iti__flag { background-image: url("/assets/intl-tel-input/img/flags@2x.png"); }
}

Restart the dev server after changes.

Mobile Responsiveness

The component is fully responsive and optimized for mobile devices:

Touch-friendly targets: All interactive elements meet the 44x44px minimum touch target size
Prevents iOS zoom: Input font size is set to 16px to prevent automatic zoom on focus
Responsive dropdown: Country list adapts to screen size and viewport height
Safe area support: Respects safe area insets on notched devices (iPhone X+)
Touch optimizations: Better tap feedback and scrolling on touch devices

Ensure your app includes a proper viewport meta tag:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=5.0, user-scalable=yes">

Quick start (Reactive Forms)

// app.component.ts
import { Component, inject } from '@angular/core';
import { ReactiveFormsModule, FormBuilder, Validators } from '@angular/forms';
import { JsonPipe } from '@angular/common';
import { NgxsmkTelInputComponent, IntlTelI18n, CountryMap } from 'ngxsmk-tel-input';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ReactiveFormsModule, NgxsmkTelInputComponent, JsonPipe],
  template: `
    <form [formGroup]="fg" style="max-width:420px;display:grid;gap:12px">
        <ngxsmk-tel-input
        formControlName="phone"
        label="Phone"
        hint="Include area code"
        dir="ltr"
        [initialCountry]="'US'"
        [preferredCountries]="['US','GB','AU']"
        [i18n]="enLabels"
        [localizedCountries]="enCountries"
        [separateDialCode]="true"         <!-- dial code after the flag -->
        [formatWhenValid]="'typing'"      <!-- live mask only when valid -->
        [lockWhenValid]="true"            <!-- stop extra digits once valid -->
      ></ngxsmk-tel-input>

      <pre>Value: {{ fg.value | json }}</pre>
    </form>
  `
})
export class AppComponent {
  private readonly fb = inject(FormBuilder);
  fg = this.fb.group({ phone: ['', Validators.required] });

  // English UI labels (dropdown/search/ARIA)
  enLabels: IntlTelI18n = {
    selectedCountryAriaLabel: 'Selected country',
    countryListAriaLabel: 'Country list',
    searchPlaceholder: 'Search country',
    zeroSearchResults: 'No results',
    noCountrySelected: 'No country selected'
  };

  // Optional: only override the names you care about
  enCountries: CountryMap = {
    US: 'United States',
    GB: 'United Kingdom',
    AU: 'Australia',
    CA: 'Canada'
  };
}

Value semantics: the form control value is E.164 (e.g., +14155550123) when valid, or null when empty/invalid.

Using Signals with Reactive Forms

You can leverage Angular Signals in combination with Reactive Forms to dynamically control input configurations (such as changing countries, placeholders, or themes) or reactively bind metadata (such as carrier info or format suggestions).

import { Component, inject, signal } from '@angular/core';
import { ReactiveFormsModule, FormBuilder } from '@angular/forms';
import { NgxsmkTelInputComponent, FormatSuggestion, CarrierInfo } from 'ngxsmk-tel-input';

@Component({
  selector: 'app-signup',
  standalone: true,
  imports: [ReactiveFormsModule, NgxsmkTelInputComponent],
  template: `
    <form [formGroup]="form">
      <ngxsmk-tel-input
        formControlName="phone"
        [initialCountry]="countryCode()"
        [placeholder]="placeholder()"
        [theme]="appTheme()"
        (inputChange)="onInputChange($event)">
      </ngxsmk-tel-input>
    </form>

    @if (carrier()) {
      <p>Detected Carrier: {{ carrier()?.carrierName }}</p>
    }
    @if (suggestion()) {
      <p>Format suggestion: {{ suggestion()?.formatted }}</p>
    }
  `
})
export class SignupComponent {
  private readonly fb = inject(FormBuilder);
  
  // Configurations managed as Signals
  countryCode = signal('US');
  placeholder = signal('Enter your mobile number');
  appTheme = signal<'light' | 'dark' | 'auto'>('auto');

  // Real-time metadata signals
  carrier = signal<CarrierInfo | null>(null);
  suggestion = signal<FormatSuggestion | null>(null);

  form = this.fb.group({
    phone: ['']
  });

  onInputChange(event: any) {
    this.carrier.set(event.intelligence?.carrier || null);
    this.suggestion.set(event.intelligence?.suggestion || null);
  }
}

Template‑driven usage

<form #f="ngForm">
  <ngxsmk-tel-input name="phone" [(ngModel)]="phone"></ngxsmk-tel-input>
</form>
<!-- phone is an E.164 string or null -->

Localization & RTL

You can localize the dropdown/search labels and override country names.

Korean example

<ngxsmk-tel-input
  [initialCountry]="'KR'"
  [preferredCountries]="['KR','US','JP']"
  [i18n]="koLabels"
  [localizedCountries]="koCountries">
</ngxsmk-tel-input>

// in component
koLabels = {
  selectedCountryAriaLabel: '선택한 국가',
  countryListAriaLabel: '국가 목록',
  searchPlaceholder: '국가 검색',
  zeroSearchResults: '결과 없음',
  noCountrySelected: '선택된 국가 없음'
};

koCountries = {
  KR: '대한민국',
  US: '미국',
  JP: '일본',
  CN: '중국'
};

Arabic + RTL example

<ngxsmk-tel-input
  dir="rtl"
  label="الهاتف"
  hint="اكتب رمز المنطقة"
  [initialCountry]="'AE'"
  [preferredCountries]="['AE','SA','EG']"
  [i18n]="arLabels"
  [localizedCountries]="arCountries"
  [dropdownAttachToBody]="false"  <!-- so popup inherits rtl from host -->
></ngxsmk-tel-input>

API

Inputs

Name	Type	Default	Description
`initialCountry`	`CountryCode \| 'auto'`	`'US'`	Starting country (also respected when initial form value is `''`). `'auto'` uses geoIp stub (`US` by default).
`preferredCountries`	`CountryCode[]`	`['US','GB']`	Pin these at the top.
`onlyCountries`	`CountryCode[]`	—	Limit selectable countries.
`excludeCountries`	`CountryCode[]`	`[]`	Exclude specific countries from the dropdown list.
`searchPlaceholder`	`string`	`''`	Custom placeholder text for the dropdown search input.
`showFlags`	`boolean`	`true`	Hide flags completely for minimalist/text-only layouts.
`searchCountryFlag`	`boolean`	`true`	Hide flag icons inside the country dropdown list.
`nationalDisplay`	`'formatted' \| 'digits'`	`'formatted'`	Controls visible input format. Value still emits E.164.
`separateDialCode`	`boolean`	`true`	Show dial code outside the input.
`allowDropdown`	`boolean`	`true`	Enable/disable dropdown.
`placeholder`	`string`	—	Input placeholder.
`autocomplete`	`string`	`'tel'`	Native autocomplete.
`disabled`	`boolean`	`false`	Disable the control.
`label`	`string`	—	Optional floating label text.
`hint`	`string`	—	Helper text below the control.
`errorText`	`string`	—	Custom error text.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Control height/typography.
`variant`	`'outline' \| 'filled' \| 'underline'`	`'outline'`	Visual variant.
`showClear`	`boolean`	`true`	Show a clear (×) button when not empty.
`autoFocus`	`boolean`	`false`	Focus on init.
`selectOnFocus`	`boolean`	`false`	Select all text on focus.
`formatWhenValid`	`'off' \| 'blur' \| 'typing'`	`'typing'`	When to format the display value.
`showErrorWhenTouched`	`boolean`	`true`	Show error styles only after blur.
`showErrorMsg`	`boolean`	`true`	Show component's internal validation error message text.
`dropdownAttachToBody`	`boolean`	`true`	Attach dropdown to `<body>` (avoids clipping/overflow).
`dropdownZIndex`	`number`	`2000`	Z‑index for dropdown panel.
`i18n`	`IntlTelI18n`	—	Localize dropdown/search/ARIA labels.
`localizedCountries`	`Partial<Record<CountryCode, string>>`	—	Override country display names (ISO-2 keys).
`dir`	`'ltr' \| 'rtl'`	`'ltr'`	Text direction for the control.
`autoPlaceholder`	`'off' \| 'polite' \| 'aggressive'`	`'off'`	Example placeholders. Requires `utilsScript` unless `off`.
`utilsScript`	`string`	—	Path/URL to `utils.js` (needed for example placeholders).
`customPlaceholder`	`(example: string, country: any) => string`	—	Transform the example placeholder.
`clearAriaLabel`	`string`	`'Clear phone number'`	ARIA label for the clear button.
`lockWhenValid`	`boolean`	`true`	Prevent appending extra digits once the number is valid (editing/replacing still allowed).
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Theme preference for the component.

CountryCode is the ISO‑2 uppercase code from libphonenumber-js (e.g. US, GB).

Outputs

Event	Payload	Description
`countryChange`	`{ iso2: CountryCode }`	Fired when selected country changes.
`validityChange`	`boolean`	Fired when validity flips.
`inputChange`	`{ raw: string; e164: string \| null; iso2: CountryCode }`	Emitted on every keystroke.

Public methods

focus(): void
selectCountry(iso2: CountryCode): void

Formatting & validity behavior

No formatting while invalid. As-you-type masking only starts when the digits form a valid number for the selected country.
Sri Lanka / “trunk 0”: a national format may include a leading 0 (e.g., 071…). The emitted E.164 always excludes it (+94 71…)—this is expected.
Lock when valid: with lockWhenValid enabled, once the number is valid, appending more digits is blocked (you can still delete/replace).

For rare patterns not covered by libphonenumber-js, the control falls back to raw digits (no forced mask) until it becomes valid.

Theming

CSS Variables

Override on the element or a parent container:

<ngxsmk-tel-input style="
  --tel-border:#cbd5e1;
  --tel-ring:#22c55e;
  --tel-radius:14px;
  --tel-dd-item-hover: rgba(34,197,94,.12);
  --tel-dd-z: 3000;
"></ngxsmk-tel-input>

Available tokens:

Input: --tel-bg, --tel-fg, --tel-border, --tel-border-hover, --tel-ring, --tel-placeholder, --tel-error, --tel-radius, --tel-focus-shadow
Dropdown: --tel-dd-bg, --tel-dd-border, --tel-dd-shadow, --tel-dd-radius, --tel-dd-item-hover, --tel-dd-search-bg, --tel-dd-z

Theme Support

The component supports light, dark, and auto themes:

import { NgxsmkTelInputComponent, ThemeService } from 'ngxsmk-tel-input';

// Component-level theme
<ngxsmk-tel-input [theme]="'dark'"></ngxsmk-tel-input>

// Global theme management
@Component({})
export class MyComponent {
  private themeService = inject(ThemeService);
  
  setDarkTheme() {
    this.themeService.setTheme('dark');
  }
  
  // Subscribe to theme changes
  theme$ = this.themeService.currentTheme$;
}

Themes:

'light': Light theme
'dark': Dark theme
'auto': Automatically follows system preference (default)

Dark mode: wrap in a .dark parent or use [theme]="'dark'" — tokens adapt automatically.

Validation patterns

<ngxsmk-tel-input formControlName="phone"></ngxsmk-tel-input>

<div class="error" *ngIf="fg.get('phone')?.hasError('required')">Phone is required</div>
<div class="error" *ngIf="fg.get('phone')?.hasError('phoneInvalid')">Please enter a valid phone number</div>
<div class="error" *ngIf="fg.get('phone')?.hasError('phoneInvalidCountryCode')">Invalid country code</div>

Enhanced Validation Features

The component now includes enhanced validation that detects and handles various invalid phone number scenarios:

Invalid Country Code Detection

Input: "1123456789" or "99123456789"
Error: phoneInvalidCountryCode
Reason: "11" and "99" are not valid country codes

Valid Country Code, Invalid Number

Input: "+9111023533" (India country code, Delhi area code, but incomplete subscriber number)
Error: phoneInvalid
Reason: Valid country/area codes but invalid number format

Valid Numbers

Input: "+12025551234" (US), "+442071234567" (UK), "+91112345678" (India)
Status: Valid
Output: E.164 format string

When valid → control value = E.164 string
When invalid/empty → value = null, and validator sets appropriate error type

Need national string instead of E.164? Use (inputChange) and store raw/national yourself, or adapt the emitter to output national.

SSR notes

The library lazy‑imports intl-tel-input only in the browser (guards with isPlatformBrowser).
No window/document usage on the server path.

Local development

This repo is an Angular workspace with a library.

# Build the library
ng build ngxsmk-tel-input

# Option A: use it inside a demo app in the same workspace
ng serve demo

# Option B: install locally via tarball in another app
cd dist/ngxsmk-tel-input && npm pack
# in your other app
npm i ../path-to-workspace/dist/ngxsmk-tel-input/ngxsmk-tel-input-<version>.tgz

Workspace aliasing via tsconfig.paths also works (map "ngxsmk-tel-input": ["dist/ngxsmk-tel-input"]).

Troubleshooting

UI looks unstyled / bullets in dropdown Add the CSS and assets in angular.json (see Install). Restart the dev server.

Flags don’t show Ensure the assets copy exists under /assets/intl-tel-input/img and add the CSS override block above.

TS2307: Cannot find module 'ngxsmk-tel-input' Build the library first so dist/ngxsmk-tel-input exists. If using workspace aliasing, add a paths entry to the root tsconfig.base.json.

Peer dependency conflict when installing The lib peers are @angular/* >=17. Ensure your app uses Angular 17 or higher.

Vite/Angular “Failed to resolve import …” Clear .angular/cache, rebuild the lib, and restart ng serve.

License

MIT

Credits

UI powered by intl-tel-input
Parsing & validation by libphonenumber-js

Last updated: 2026-06-07

Name		Name	Last commit message	Last commit date
Latest commit History 87 Commits
.changeset		.changeset
.github		.github
.storybook		.storybook
.vscode		.vscode
projects		projects
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
angular.json		angular.json
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ngxsmk-tel-input

Try it live on StackBlitz

Features

Requirements

Zone.js Compatibility

Install

Add styles & flag assets (in your app, not the library)

Mobile Responsiveness

Quick start (Reactive Forms)

Using Signals with Reactive Forms

Template‑driven usage

Localization & RTL

API

Inputs

Outputs

Public methods

Formatting & validity behavior

Theming

CSS Variables

Theme Support

Validation patterns

Enhanced Validation Features

Invalid Country Code Detection

Valid Country Code, Invalid Number

Valid Numbers

SSR notes

Local development

Troubleshooting

License

Credits

About

Uh oh!

Releases 6

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ngxsmk-tel-input

Try it live on StackBlitz

Features

Requirements

Zone.js Compatibility

Install

Add styles & flag assets (in your app, not the library)

Mobile Responsiveness

Quick start (Reactive Forms)

Using Signals with Reactive Forms

Template‑driven usage

Localization & RTL

API

Inputs

Outputs

Public methods

Formatting & validity behavior

Theming

CSS Variables

Theme Support

Validation patterns

Enhanced Validation Features

Invalid Country Code Detection

Valid Country Code, Invalid Number

Valid Numbers

SSR notes

Local development

Troubleshooting

License

Credits

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 6

Contributors

Uh oh!

Languages