oziSelect

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

Descripción

Plugin de selección personalizada para interfaces web, desarrollado para reemplazar los selects tradicionales por una experiencia más rica, visual y flexible. Permite trabajar con selección simple o múltiple, mostrar elementos con imagen, texto o HTML personalizado, organizar opciones por grupos e integrar la selección directamente con formularios mediante campos hidden generados automáticamente a partir de cualquier campo presente en el JSON de opciones.

Ofrece soporte para búsqueda local y búsqueda remota, posibilitando filtrar opciones existentes en el navegador o consultar nuevos resultados en el servidor mientras el usuario escribe. Recomendado para escenarios donde un select estándar no ofrece suficiente flexibilidad — como listas con imágenes, selecciones múltiples con etiquetas visuales, agrupamiento de opciones y carga dinámica vía AJAX.

Ejemplos

[1] Selección simple

<div data-ozi-select="comunidades"></div>

<script type="application/json" data-ozi-select-options="comunidades">
[
    { "value": "AND", "label": "Andalucía" },
    { "value": "CAT", "label": "Cataluña" },
    { "value": "MAD", "label": "Madrid" }
]
</script>

[2] Con iconos

Usa data-ozi-select-value-icon y data-ozi-select-search-icon con cualquier biblioteca de iconos.

<div
    data-ozi-select="comunidades"
    data-ozi-select-value-placeholder="Selecciona una comunidad..."
    data-ozi-select-value-icon="bi bi-geo-alt"
    data-ozi-select-search-placeholder="Buscar..."
    data-ozi-select-search-icon="bi bi-search">
</div>

[3] Con imagen

Usa el campo image en el JSON para mostrar imágenes en las opciones, preview y etiquetas.

<div
    data-ozi-select="paises"
    data-ozi-select-value-placeholder="Selecciona un país..."
    data-ozi-select-value-icon="bi bi-globe"
    data-ozi-select-search-icon="bi bi-search"
    data-ozi-select-list="150px">
</div>

<script type="application/json" data-ozi-select-options="paises">
[
    { "value": "MX", "label": "México",    "labelHtml": "Américas", "image": "/image/flags/mx.jpg" },
    { "value": "ES", "label": "España",    "labelHtml": "Europa",   "image": "/image/flags/es.jpg" }
]
</script>

[4] Selección múltiple

<div
    data-ozi-select="comunidades"
    data-ozi-select-multiple
    data-ozi-select-value-placeholder="Selecciona comunidades..."
    data-ozi-select-value-icon="bi bi-geo-alt"
    data-ozi-select-search-icon="bi bi-search"
    data-ozi-select-list="150px">
</div>

<script type="application/json" data-ozi-select-options="comunidades">
[
    { "value": "CAT", "label": "Cataluña", "labelHtml": "Este" },
    { "value": "MAD", "label": "Madrid",   "labelHtml": "Centro" }
]
</script>

[5] Múltiple con grupos

Usa el campo group en el JSON para organizar las opciones en grupos visuales.

<div
    data-ozi-select="comunidades"
    data-ozi-select-multiple
    data-ozi-select-list="220px">
</div>

<script type="application/json" data-ozi-select-options="comunidades">
[
    { "value": "PVA", "label": "País Vasco", "group": "Norte" },
    { "value": "CAT", "label": "Cataluña",   "group": "Este" },
    { "value": "MAD", "label": "Madrid",     "group": "Centro" }
]
</script>

[6] Seleccionar todos por grupo

Usa data-ozi-select-multiple-group — haz clic en el grupo para seleccionar o eliminar todos los elementos a la vez.

<div
    data-ozi-select="comunidades"
    data-ozi-select-multiple-group
    data-ozi-select-list="220px"
    data-ozi-select-required>
</div>

[7] Búsqueda remota — mínimo

Usa data-ozi-select-zld-url para buscar opciones vía AJAX. El JSON inicial está vacío.

<div
    data-ozi-select="comunidades"
    data-ozi-select-multiple-group
    data-ozi-select-zld-url="/api/comunidades">
</div>

<script type="application/json" data-ozi-select-options="comunidades">[]</script>

[8] Búsqueda remota — completa

POST con parámetros extra, imágenes, delay y log activado.

<div
    data-ozi-select="comunidades"
    data-ozi-select-multiple-group
    data-ozi-select-value-placeholder="Selecciona comunidades..."
    data-ozi-select-image-dimension="50px,40px"
    data-ozi-select-zld-url="/api/comunidades/buscar"
    data-ozi-select-zld-method="POST"
    data-ozi-select-zld-param="search"
    data-ozi-select-zld-item-name="empresa_id:15, estado:activo"
    data-ozi-select-zld-min="1"
    data-ozi-select-zld-delay="0"
    data-ozi-select-zld-log="true">
</div>

<script type="application/json" data-ozi-select-options="comunidades">[]</script>

Características

• Selección simple o múltiple — con etiquetas visuales en modo múltiple
• Iconos personalizables — value-icon y search-icon con cualquier biblioteca
• HTML personalizado — muestra imágenes, subLabel o HTML en opciones y preview
• Agrupamiento de opciones — campo group en JSON organiza visualmente
• Seleccionar por grupo — multiple-group selecciona/elimina todos de un grupo
• Búsqueda local — filtra opciones ya cargadas en el navegador
• Búsqueda remota — consulta el servidor vía AJAX mientras el usuario escribe
• Hidden inputs automáticos — cualquier campo JSON se convierte en input hidden
• Validación — soporte de campo obligatorio con mensaje personalizado
• API pública completa — get, set, open, close, enable, disable y más

Atributos HTML

NUEVA CARACTERÍSTICA

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

  • Formato: "canónico=alias, canónico=alias"
  • Ejemplo: data-ozi-select-as="value=codigo, label=nombre, group=region"

[1] Identificación

[2] Datos JSON — Campos de las Opciones

[3] Modo de Selección

[4] Placeholders y Visual

[5] Envío de Datos

[6] Estado y Validación

[7] Búsqueda Remota

API Pública

Evento ozi:change

$('[data-ozi-select="comunidades"]').on('ozi:change', function(e, items, instance, detail) {
    console.log(detail.value);  // valor seleccionado
    console.log(detail.items);  // array de elementos seleccionados
});