oziAutocomplete

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

Descrição

Plugin de campo de texto com sugestões automáticas para interfaces web. Transforma um <input type="text"> em um campo inteligente com dropdown de sugestões, normalizando acentos e variações de escrita durante a filtragem, e sincronizando automaticamente o valor selecionado em um <input hidden> para envio ao backend.

Suporta dois modos de operação: local — filtrando opções definidas via JSON estático — e remoto — consultando o servidor conforme o usuário digita, com debounce e cancelamento automático de requisições concorrentes. Os dois modos podem coexistir: abaixo do mínimo configurado as opções locais são exibidas; acima do mínimo, o servidor é consultado.

Exemplos

[1] Opções locais — mínimo

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

<script type="application/json" data-ozi-autocomplete-options="estado">
[
    { "value": "PR", "label": "Paraná" },
    { "value": "SC", "label": "Santa Catarina" },
    { "value": "SP", "label": "São Paulo" }
]
</script>

[2] Com hidden-name customizado e mensagens

<input type="text"
    class="form-control"
    data-ozi-autocomplete="produto"
    data-ozi-autocomplete-hidden-name="produto_id"
    data-ozi-autocomplete-msg-empty="Nenhum produto encontrado"
    data-ozi-autocomplete-msg-search="Buscando produtos..."
    placeholder="Digite um produto...">

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

[3] Busca 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="Digite o nome do cliente...">

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

[4] Local + remoto combinados

Abaixo do mínimo mostra opções locais. Acima do mínimo consulta o servidor.

<input type="text"
    class="form-control"
    data-ozi-autocomplete="cidade"
    data-ozi-autocomplete-zld-url="/api/cidades/buscar"
    data-ozi-autocomplete-zld-min="3"
    data-ozi-autocomplete-zld-delay="400"
    placeholder="Digite uma cidade...">

<script type="application/json" data-ozi-autocomplete-options="cidade">
[
    { "value": "1", "label": "São Paulo" },
    { "value": "2", "label": "Rio de Janeiro" },
    { "value": "3", "label": "Curitiba" }
]
</script>

Abaixo de 3 caracteres → mostra as opções locais. A partir de 3 → consulta /api/cidades/buscar.

[5] Uso via JavaScript — evento ozi:change

// jQuery
$('[data-ozi-autocomplete="estado"]').on('ozi:change', function(e, item, instance, detail) {
    console.log(detail.value);  // value selecionado
    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);
    });

Recursos

• Modo local — filtra opções JSON já carregadas no navegador
• Modo remoto — consulta o servidor com debounce configurável
• Modo combinado — local abaixo do mínimo, remoto acima
• Normalização — ignora acentos e variações de escrita na filtragem
• Hidden automático — gera <input hidden> sincronizado para envio
• Cancelamento automático — requisições concorrentes são canceladas
• MutationObserver — detecta e inicializa novos elementos no DOM
• Evento ozi:change — notifica seleção via jQuery e DOM nativo

Atributos HTML

Nova ferramenta

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

  Formato: "canônico=alias, canônico=alias" Exemplo: data-ozi-autocomplete-as="value=id, label=nome"

• data-ozi-autocomplete-unique → ativa validação de valor único no blur. Se o label digitado já existir na lista: limpa o campo, aplica is-invalid e exibe mensagem flutuante temporária (~2500ms). Se não existir: aplica is-valid. Evento disparado: ozi:unique-invalid

• data-ozi-autocomplete-unique-message → mensagem exibida no toast quando o valor já existe. Padrão: "Valor já existente"

[1] Campo

[2] Mensagens

[3] Opções JSON

<script type="application/json" data-ozi-autocomplete-options="chave">
[
    { "value": "1", "label": "Opção Um" },
    { "value": "2", "label": "Opção Dois" }
]
</script>

[4] Busca Remota

API Pública

Uso com conteúdo dinâmico

oziAutocompleteInitFetched($('#destino'));