NgxPhoneInput

Componente de entrada de teléfono internacional para Angular 18+, construido con Angular Material. Incluye selector de país con banderas, validación automática por longitud y soporte completo para formularios reactivos.

✨ Características

• 🌍 +35 países incluidos - Lista predeterminada con países de América, Europa y Asia
• 🎯 Integración con Reactive Forms - Implementa ControlValueAccessor y Validator
• ✅ Validación automática - Valida longitud según el país seleccionado
• 🚩 Banderas emoji - Selector visual con banderas de cada país
• 📦 Standalone Component - Sin necesidad de módulos adicionales
• ⚡ Angular Signals - Máximo rendimiento con signals
• 🎨 Personalizable - Acepta lista de países personalizada y clases CSS
• 🧹 Botón limpiar - Incluye botón para resetear el campo

📋 Requisitos

| Dependencia | Versión | |-------------|---------| | Angular | >= 18.0.0 | | Angular Material | >= 18.0.0 | | Angular CDK | >= 18.0.0 |

📦 Instalación

npm install @mstechnology/ngx-phone-input

Asegúrate de tener Angular Material configurado:

ng add @angular/material

🚀 Uso Básico

1. Importar el componente

import { NgxPhoneInput } from '@mstechnology/ngx-phone-input';

@Component({
  selector: 'app-mi-componente',
  standalone: true,
  imports: [NgxPhoneInput, ReactiveFormsModule],
  templateUrl: './mi-componente.html'
})
export class MiComponente { }

2. Usar en el template

<form [formGroup]="miFormulario">
  <lib-ngx-phone-input
    class="w-full"
    formControlName="telefono"
    initialCountryIso="CO"
    label="Teléfono celular"
    [required]="true"
    (phoneChange)="onPhoneChange($event)">
  </lib-ngx-phone-input>

  @if (miFormulario.get('telefono')?.hasError('required')) {
    <span class="error">El teléfono es requerido</span>
  }
  @if (miFormulario.get('telefono')?.hasError('invalidLength'); let error) {
    <span class="error">
      Se requieren {{ error.requiredLength }} dígitos para {{ error.countryName }}
    </span>
  }
</form>

3. Configurar en el componente

import { Component } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';
import { PhoneValue } from '@mstechnology/ngx-phone-input';

@Component({ ... })
export class MiComponente {
  miFormulario: FormGroup;

  constructor(private fb: FormBuilder) {
    this.miFormulario = this.fb.group({
      telefono: ['', Validators.required]
    });
  }

  onPhoneChange(phone: PhoneValue): void {
    console.log('Número completo:', phone.fullNumber);  // +573001234567
    console.log('Código país:', phone.countryCode);      // +57
    console.log('Número nacional:', phone.nationalNumber); // 3001234567
    console.log('Es válido:', phone.isValid);            // true/false
    console.log('País:', phone.country?.name);           // Colombia
  }
}

📖 API

Inputs

| Propiedad | Tipo | Requerido | Default | Descripción | |-----------|------|-----------|---------|-------------| | class | string | ✅ | '' | Clases CSS para el contenedor | | data | Country[] | ❌ | Lista interna | Lista de países personalizada | | initialCountryIso | string | ❌ | 'CO' | Código ISO del país inicial | | label | string | ❌ | 'Teléfono' | Etiqueta del campo | | appearance | 'fill' \| 'outline' | ❌ | 'outline' | Apariencia de Material | | showCountryName | boolean | ❌ | false | Mostrar nombre del país | | showClearButton | boolean | ❌ | true | Mostrar botón limpiar | | showHint | boolean | ❌ | true | Mostrar contador de caracteres | | required | boolean | ❌ | false | Campo requerido |

Outputs

| Evento | Tipo | Descripción | |--------|------|-------------| | phoneChange | EventEmitter<PhoneValue> | Emite información completa al cambiar |

Interfaces

interface Country {
  code: string;    // '+57'
  iso: string;     // 'CO'
  flag: string;    // '🇨🇴'
  name: string;    // 'Colombia'
  mask: string;    // '000 000 0000'
  length: number;  // 10
}

interface PhoneValue {
  fullNumber: string;      // '+573001234567'
  countryCode: string;     // '+57'
  nationalNumber: string;  // '3001234567'
  country: Country | null;
  isValid: boolean;
}

Errores de Validación

| Error | Descripción | |-------|-------------| | required | Campo vacío cuando es requerido | | minLength | Menos de 5 dígitos | | invalidLength | No coincide con longitud del país |

// Acceder a los errores
const errors = this.form.get('telefono')?.errors;

if (errors?.['invalidLength']) {
  console.log(`Se requieren ${errors['invalidLength'].requiredLength} dígitos`);
}

💡 Ejemplos Avanzados

Lista de países personalizada

import { Country } from '@mstechnology/ngx-phone-input';

misPaises: Country[] = [
  { code: '+57', iso: 'CO', flag: '🇨🇴', name: 'Colombia', mask: '000 000 0000', length: 10 },
  { code: '+1', iso: 'US', flag: '🇺🇸', name: 'USA', mask: '(000) 000-0000', length: 10 },
];

<lib-ngx-phone-input
  class="w-full"
  [data]="misPaises"
  formControlName="telefono">
</lib-ngx-phone-input>

Valor inicial programático

// Establecer valor (detecta país automáticamente)
this.form.patchValue({
  telefono: '+573001234567'
});

// Resetear
this.form.get('telefono')?.reset();

Con apariencia fill

<lib-ngx-phone-input
  class="w-full"
  appearance="fill"
  [showCountryName]="true"
  formControlName="telefono">
</lib-ngx-phone-input>

🎨 Estilos Globales (Opcional)

// Para que el panel del selector tenga scroll
::ng-deep .ngx-phone-country-panel {
  max-height: 300px;
}

// Ancho personalizado
.custom-phone {
  max-width: 400px;
}

📄 Licencia

MIT © MS Technology

¿Te resultó útil? ⭐ Dale una estrella al repositorio