oziAutocomplete

Versión: 3.0.0 — Actualizado: 2026-05-27

Descripción

Plugin de campo de texto con sugerencias automáticas para interfaces web. Transforma un <input type="text"> en un campo inteligente con dropdown de sugerencias, normalizando acentos y variaciones de escritura durante el filtrado, y sincronizando automáticamente el valor seleccionado en un <input hidden> para el envío al backend.

Soporta dos modos de operación: local — filtrando opciones definidas mediante JSON estático — y remoto — consultando el servidor mientras el usuario escribe, con debounce y cancelación automática de solicitudes concurrentes. Ambos modos pueden coexistir: por debajo del mínimo configurado se muestran las opciones locales; por encima del mínimo, se consulta el servidor.

Ejemplos

[1] Opciones locales — mínimo

<input type="text"
    class="form-control"
    data-ozi-autocomplete="estado"
    placeholder="Escribe un estado...">

<script type="application/json" data-ozi-autocomplete-options="estado">
[
    { "value": "MX", "label": "México" },
    { "value": "JAL", "label": "Jalisco" },
    { "value": "NL", "label": "Nuevo León" }
]
</script>

[2] Con hidden-name personalizado y mensajes

<input type="text"
    class="form-control"
    data-ozi-autocomplete="producto"
    data-ozi-autocomplete-hidden-name="producto_id"
    data-ozi-autocomplete-msg-empty="Ningún producto encontrado"
    data-ozi-autocomplete-msg-search="Buscando productos..."
    placeholder="Escribe un producto...">

<script type="application/json" data-ozi-autocomplete-options="producto">
[
    { "value": "1", "label": "Notebook Dell" },
    { "value": "2", "label": "Notebook Lenovo" }
]
</script>

[3] Búsqueda remota — mínimo

<input type="text"
    class="form-control"
    data-ozi-autocomplete="cliente"
    data-ozi-autocomplete-url="/api/clientes/buscar"
    data-ozi-autocomplete-min="2"
    data-ozi-autocomplete-delay="300"
    placeholder="Escribe el nombre del cliente...">

<script type="application/json" data-ozi-autocomplete-options="cliente">
[]
</script>

[4] Local + remoto combinados

Por debajo del mínimo muestra opciones locales. Por encima del mínimo consulta el servidor.

<input type="text"
    class="form-control"
    data-ozi-autocomplete="ciudad"
    data-ozi-autocomplete-zld-url="/api/ciudades/buscar"
    data-ozi-autocomplete-zld-min="3"
    data-ozi-autocomplete-zld-delay="400"
    placeholder="Escribe una ciudad...">

<script type="application/json" data-ozi-autocomplete-options="ciudad">
[
    { "value": "1", "label": "Ciudad de México" },
    { "value": "2", "label": "Guadalajara" },
    { "value": "3", "label": "Monterrey" }
]
</script>

Por debajo de 3 caracteres → muestra las opciones locales. A partir de 3 → consulta /api/ciudades/buscar.

[5] Uso vía JavaScript — evento ozi:change

// jQuery
$('[data-ozi-autocomplete="estado"]').on('ozi:change', function(e, item, instance, detail) {
    console.log(detail.value);  // valor seleccionado
    console.log(detail.item);   // { value, label }
});

// DOM nativo
document.querySelector('[data-ozi-autocomplete="estado"]')
    .addEventListener('ozi:change', function(e) {
        console.log(e.detail.value);
        console.log(e.detail.item);
    });

Características

• Modo local — filtra opciones JSON ya cargadas en el navegador
• Modo remoto — consulta el servidor con debounce configurable
• Modo combinado — local por debajo del mínimo, remoto por encima
• Normalización — ignora acentos y variaciones de escritura en el filtrado
• Hidden automático — genera un <input hidden> sincronizado para el envío
• Cancelación automática — las solicitudes concurrentes se cancelan automáticamente
• MutationObserver — detecta e inicializa nuevos elementos en el DOM
• Evento ozi:change — notifica la selección vía jQuery y DOM nativo

Atributos HTML

Nuevas características

• data-ozi-autocomplete-as → mapea campos del JSON externo a los nombres canónicos del plugin (value, label), permitiendo consumir cualquier API sin transformar los datos en el backend.

  Formato: "canónico=alias, canónico=alias" Ejemplo: data-ozi-autocomplete-as="value=id, label=nombre"

• data-ozi-autocomplete-unique → activa validación de valor único al perder el foco. Si el label escrito ya existe en la lista: limpia el campo, aplica is-invalid y muestra un mensaje flotante temporal (~2500ms). Si no existe: aplica is-valid. Evento disparado: ozi:unique-invalid

• data-ozi-autocomplete-unique-message → mensaje mostrado en el toast cuando el valor ya existe. Por defecto: "Valor ya existente"

[1] Campo

[2] Mensajes

[3] Opciones JSON

<script type="application/json" data-ozi-autocomplete-options="clave">
[
    { "value": "1", "label": "Opción Uno" },
    { "value": "2", "label": "Opción Dos" }
]
</script>

[4] Búsqueda Remota

API Pública

Uso con contenido dinámico

oziAutocompleteInitFetched($('#destino'));