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 national with nationalMode)
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
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
New: Masking & caret-friendly as-you-type formatting (optional)
New: Format only when valid (formatWhenValid) and lock once valid (lockWhenValid) to prevent extra digits

✅ Requirements

Angular 17 – 19
Node 18 or 20

Library peerDependencies target Angular >=17 <20. Your app can be 17, 18, or 19.

📦 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/[email protected]"); }
}

Restart the dev server after changes.

🚀 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.

📝 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. `'auto'` uses geoIp stub (`US` by default).
`preferredCountries`	`CountryCode[]`	`['US','GB']`	Pin these at the top.
`onlyCountries`	`CountryCode[]`	—	Limit selectable countries.
`nationalMode`	`boolean`	`false`	If `true`, display national format in the input. Value still emits E.164.
`separateDialCode`	`boolean`	`false`	Show dial code outside the input.
`allowDropdown`	`boolean`	`true`	Enable/disable dropdown.
`placeholder`	`string`	`'Enter phone number'`	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.
`formatOnBlur`	`boolean`	`true`	Pretty‑print on blur (national if `nationalMode`).
`showErrorWhenTouched`	`boolean`	`true`	Show error styles only after blur.
`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'`	`'polite'`	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).

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

Dark mode: wrap in a .dark parent — 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 <20. Upgrade your app or install a compatible version.

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: 2025-08-29

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.changeset		.changeset
.github		.github
.vscode		.vscode
projects		projects
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
OPTIMIZATION_NOTES.md		OPTIMIZATION_NOTES.md
README.md		README.md
SECURITY.md		SECURITY.md
THEME_DOCUMENTATION.md		THEME_DOCUMENTATION.md
angular.json		angular.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

ngxsmk-tel-input

🚀 Try it live on StackBlitz

✨ Features

✅ Requirements

📦 Install

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

🚀 Quick start (Reactive Forms)

📝 Template‑driven usage

🈺 Localization & RTL

⚙️ API

Inputs

Outputs

Public methods

🧠 Formatting & validity behavior

🎨 Theming (CSS variables)

✔️ 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

Packages

Languages

License

toozuuu/ngxsmk-tel-input

Folders and files

Latest commit

History

Repository files navigation

ngxsmk-tel-input

🚀 Try it live on StackBlitz

✨ Features

✅ Requirements

📦 Install

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

🚀 Quick start (Reactive Forms)

📝 Template‑driven usage

🈺 Localization & RTL

⚙️ API

Inputs

Outputs

Public methods

🧠 Formatting & validity behavior

🎨 Theming (CSS variables)

✔️ Validation patterns

Enhanced Validation Features

Invalid Country Code Detection

Valid Country Code, Invalid Number

Valid Numbers

🌐 SSR notes

🧪 Local development

🧯 Troubleshooting

📃 License

🙌 Credits

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages