oziSelect

Versão: 4.3.2 — Atualizado em: 2026-04-29

Descrição

Plugin de seleção customizada para interfaces web, desenvolvido para substituir selects tradicionais por uma experiência mais rica, visual e flexível. Permite trabalhar com seleção simples ou múltipla, exibir itens com imagem, texto ou HTML customizado, organizar opções por grupos e integrar a seleção diretamente com formulários por meio de campos hidden gerados automaticamente a partir de qualquer campo presente no JSON de opções.

Oferece suporte a busca local e busca remota, possibilitando filtrar opções existentes no navegador ou consultar novos resultados no servidor conforme o usuário digita. Indicado para cenários onde um select comum não oferece flexibilidade suficiente — como listas com imagens, múltiplas escolhas com tags visuais, agrupamento de opções e preenchimento dinâmico via AJAX.

Exemplos

[1] Seleção simples

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

<script type="application/json" data-ozi-select-options="estados">
[
    { "value": "AC", "label": "Acre" },
    { "value": "AL", "label": "Alagoas" },
    { "value": "SP", "label": "São Paulo" }
]
</script>

[2] Com ícones

Use data-ozi-select-value-icon e data-ozi-select-search-icon com qualquer biblioteca de ícones.

<div
    data-ozi-select="estados"
    data-ozi-select-value-placeholder="Selecione um estado..."
    data-ozi-select-value-icon="bi bi-geo-alt"
    data-ozi-select-search-placeholder="Pesquisar..."
    data-ozi-select-search-icon="bi bi-search">
</div>

[3] Com imagem

Use o campo image no JSON para exibir imagens nas opções, preview e tags.

<div
    data-ozi-select="estados"
    data-ozi-select-value-placeholder="Selecione estados/Região..."
    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="estados">
[
    { "value": "PR", "label": "Paraná", "labelHtml": "Sul", "image": "/image/bandeiras/bandeira-estado-parana.jpg" },
    { "value": "SP", "label": "São Paulo", "labelHtml": "Sudeste", "image": "/image/bandeiras/bandeira-estado-sao-paulo.jpg" }
]
</script>

[4] Múltipla seleção

<div
    data-ozi-select="estados"
    data-ozi-select-multiple
    data-ozi-select-value-placeholder="Selecione estados..."
    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="estados">
[
    { "value": "AC", "label": "Acre", "labelHtml": "Norte" },
    { "value": "SP", "label": "São Paulo", "labelHtml": "Sudeste" }
]
</script>

[5] Múltipla com grupos

Use o campo group no JSON para organizar as opções por grupos visuais.

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

<script type="application/json" data-ozi-select-options="estados">
[
    { "value": "AC", "label": "Acre",     "group": "Região Norte" },
    { "value": "SP", "label": "São Paulo","group": "Região Sudeste" },
    { "value": "PR", "label": "Paraná",   "group": "Região Sul" }
]
</script>

[6] Selecionar todos por grupo

Use data-ozi-select-multiple-group — clique no grupo para selecionar ou remover todos os itens de uma vez.

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

[7] Busca remota — mínimo

Use data-ozi-select-zld-url para buscar opções via AJAX. O JSON inicial fica vazio.

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

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

[8] Busca remota — completo

POST com parâmetros extras, imagens, delay e log ativado.

<div
    data-ozi-select="estados"
    data-ozi-select-multiple-group
    data-ozi-select-value-placeholder="Selecione estados..."
    data-ozi-select-image-dimension="50px,40px"
    data-ozi-select-zld-url="/api/estados/buscar"
    data-ozi-select-zld-method="POST"
    data-ozi-select-zld-param="search"
    data-ozi-select-zld-item-name="empresa_id:15, status:ativo"
    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="estados">[]</script>

Recursos

• Seleção simples ou múltipla — com tags visuais no modo múltiplo
• Ícones customizáveis — value-icon e search-icon com qualquer biblioteca
• HTML customizado — exibe imagens, subLabel ou HTML nas opções e preview
• Agrupamento de opções — campo group no JSON organiza visualmente
• Selecionar por grupo — multiple-group seleciona/remove todos de um grupo
• Busca local — filtra opções já carregadas no navegador
• Busca remota — consulta o servidor via AJAX conforme o usuário digita
• Hidden inputs automáticos — qualquer campo do JSON vira input hidden
• Validação — suporte a campos obrigatórios com mensagem customizada
• API pública completa — get, set, open, close, enable, disable e mais

Atributos HTML

NOVA FERRAMENTA

• data-ozi-select-as → mapeia campos do JSON externo para os nomes canônicos do plugin (value, label, image, etc.), permitindo consumir qualquer API sem transformar os dados no back-end

  • Formato: "canônico=alias, canônico=alias"
  • Exemplo: data-ozi-select-as="value=uf, label=estado, group=regiao"

[1] Identificação

[2] Dados JSON — Campos das Opções

[3] Modo de Seleção

[4] Placeholders e Visual

[5] Submissão de Dados

[6] Estado e Validação

[7] Busca Remota

API Pública

Evento ozi:change

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