TdnInputTag

Paquete: @tiendana/ngx-core/forms

Componente de entrada para múltiples valores en forma de etiquetas (tags). Ideal para palabras clave, categorías, destinatarios de email, o cualquier lista de valores cortos.

Características

• ✅ Múltiples valores: Gestiona arrays de strings fácilmente
• ✅ Teclado optimizado: Enter o coma para agregar, Backspace para eliminar
• ✅ Validación con regex: Valida el formato de cada etiqueta antes de agregar
• ✅ Control de duplicados: Opción para permitir o rechazar valores duplicados
• ✅ Límite de etiquetas: Define cantidad máxima de tags permitidos
• ✅ Pegado inteligente: Soporta pegar múltiples valores separados por comas
• ✅ Auto-agregar en blur: Agrega automáticamente el valor al perder el foco
• ✅ Personalización completa: Textos, teclas, íconos y comportamiento configurables

API

Inputs

Propiedad	Tipo	Default	Descripción
regexPattern	string | RegExp	'.*'	Patrón regex para validar cada etiqueta antes de agregarla
settings	TagInputSettings	undefined	Objeto de configuración completo
placeholder	string	'Escriba y presione Enter o coma para agregar'	Texto de ayuda en el input; también es el aria-label del campo
errorMessage	string	'La etiqueta no cumple con el formato requerido'	Se combina con la configuración, pero el componente nunca lo muestra (ver nota)
maxTags	number	Infinity	Cantidad máxima de etiquetas permitidas
allowDuplicates	boolean	false	Permitir etiquetas duplicadas
showPlaceholder	boolean	false	Muestra el placeholder aunque el campo vacío no tenga el foco

Outputs

Evento	Tipo	Descripción
focus	void	El campo recibe el foco
blur	void	El campo pierde el foco

Atributos HTML

Atributo	Tipo	Descripción
tdnControl	Directive	Conecta con FormControl y activa estados visuales (touched, dirty, valid)
formControlName	string	Nombre del control en un FormGroup
[formControl]	FormControl	Referencia directa a un FormControl

Configuración

Interfaz TagInputSettings

interface TagInputSettings {
    placeholder?: string;          // Texto del placeholder
    errorMessage?: string;          // Sin efecto visible: nunca se muestra
    maxTags?: number;               // Máximo de tags permitidos
    allowDuplicates?: boolean;      // Permitir duplicados
    addKeys?: string[];             // Teclas para agregar tags (default: ['Enter', ','])
    removeKey?: string;             // Tecla para eliminar último tag (default: 'Backspace')
    icons?: {
        clear?: string | SafeHtml;  // Ícono del botón limpiar
    };
}

errorMessage no se muestra

errorMessage (el input y settings.errorMessage) se combina con la configuración, pero el componente no lo dibuja en ningún sitio. Una etiqueta que no cumple regexPattern simplemente se descarta en silencio, y lo mismo ocurre al superar maxTags o al repetir un valor sin allowDuplicates. Si necesitas avisar al usuario, usa un validador y tdnErrors.

Clases del host

tdn-input-tag y disabled.

Ejemplos y Demos

Uso Básico

Cargando demo...

Ver código

Con Valores Iniciales

Cargando demo...

Ver código

Validación con Regex (Solo Letras)

Cargando demo...

Ver código

Validación Email

Cargando demo...

Ver código

Máximo de Etiquetas

Cargando demo...

Ver código

Permitir Duplicados

Cargando demo...

Ver código

Configuración Personalizada

Cargando demo...

Ver código

Con Validación Required

Cargando demo...

Ver código

Validación Personalizada (Mínimo de Tags)

Cargando demo...

Ver código

Ejemplo Completo

Cargando demo...

Ver código

Funcionalidades Avanzadas

Gestión del Teclado

• Enter o Coma: Por defecto agregan la etiqueta actual
• Backspace: Elimina la última etiqueta cuando el input está vacío
• Blur: Auto-agrega el valor actual si no está vacío
• Configurables: Personaliza con addKeys y removeKey

Placeholder

El placeholder solo se muestra cuando no hay etiquetas, y por defecto únicamente mientras el campo tiene el foco. Con [showPlaceholder]="true" también se muestra con el campo vacío y sin foco. En cuanto hay una etiqueta, el placeholder desaparece en ambos casos.

Pegado de Múltiples Valores

El componente soporta pegar múltiples valores separados por comas:

Angular, React, Vue

Se convertirá automáticamente en 3 etiquetas separadas.

Validación por Regex

Cada etiqueta se valida antes de ser agregada. Si no cumple el patrón, simplemente no se agrega al array: no se muestra ningún mensaje (ver errorMessage).

Otros comportamientos

• Un valor null o que no sea un array se escribe como [].
• Los duplicados se rechazan salvo con allowDuplicates, y maxTags se aplica en silencio.
• El botón de quitar cada etiqueta tiene aria-label="Eliminar etiqueta".

Buenas Prácticas

✅ Hacer

• Usar regexPattern para validar formato de etiquetas
• Establecer maxTags cuando hay límite conocido
• Avisar al usuario de los formatos admitidos con el placeholder o un texto de ayuda, ya que errorMessage no se muestra
• Deshabilitar duplicados por defecto (allowDuplicates: false)
• Usar validadores de array (minLengthArray, custom validators)
• Combinar con tdnErrors para retroalimentación visual

❌ Evitar

• Omitir validación cuando el formato es crítico
• Permitir infinitas etiquetas sin límite razonable
• Usar para listas largas (considerar TdnSelect con multi-selección)
• Validar solo en submit (validar en tiempo real con regex)

Accesibilidad

• ✅ Label asociado con <label> dentro de <tdn-form-element>
• ✅ Placeholder descriptivo por defecto
• ✅ El campo usa el placeholder como aria-label
• ✅ Navegación por teclado completa
• ✅ Estados visuales para disabled, touched, valid

Personalización Avanzada

Token de Configuración Global

Puedes configurar valores por defecto para todos los componentes TdnInputTag usando el token TDN_TAG_INPUT_DEFAULT_SETTINGS (nota: este token no lleva el sufijo _TOKEN que tienen los de otros inputs).

Configuración Global

import { ApplicationConfig } from '@angular/core';
import { TDN_TAG_INPUT_DEFAULT_SETTINGS } from '@tiendana/ngx-core/forms';

export const appConfig: ApplicationConfig = {
    providers: [
        {
            provide: TDN_TAG_INPUT_DEFAULT_SETTINGS,
            useValue: {
                placeholder: 'Agregar valor',
                errorMessage: 'Formato inválido',
                maxTags: 20,
                allowDuplicates: false,
                addKeys: ['Enter', ',', ' '],
                removeKey: 'Backspace',
                icons: {
                    clear: '<i class="material-symbols-rounded">close</i>'
                }
            }
        }
    ]
};

También puedes configurar a nivel de módulo o componente:

@Component({
    providers: [
        {
            provide: TDN_TAG_INPUT_DEFAULT_SETTINGS,
            useValue: { /* tu configuración */ }
        }
    ]
})
export class MyComponent { }

Componentes Relacionados

• TdnFormElement - Wrapper para estilos consistentes
• tdnControl - Seguimiento de estado con signals
• TdnSelect - Para elegir entre valores conocidos