oziCheck

Versão: 2.2.0 — Atualizado em: 2026-06-01

Descrição

Plugin para gerenciamento de checkboxes hierárquicos em 3 níveis por grupo. Controla ativação do grupo, marcação em massa e sincronização automática do estado entre os itens. Suporta estado indeterminate quando apenas parte dos itens está marcada, e funciona tanto em carregamento normal quanto em conteúdo inserido dinamicamente via fetch ou ZLD.

Hierarquia de controle: switch → group → item

Exemplos

[1] Grupo simples — sem switch

Apenas group + item. Tristate automático no group conforme estado dos itens.

<input type="checkbox" data-ozi-check-group="norte"> Selecionar todos

<input type="checkbox" data-ozi-check-item="norte" value="acre">      Acre
<input type="checkbox" data-ozi-check-item="norte" value="amapa">     Amapá
<input type="checkbox" data-ozi-check-item="norte" value="amazonas">  Amazonas
<input type="checkbox" data-ozi-check-item="norte" value="para">      Pará
<input type="checkbox" data-ozi-check-item="norte" value="rondonia">  Rondônia
<input type="checkbox" data-ozi-check-item="norte" value="roraima">   Roraima
<input type="checkbox" data-ozi-check-item="norte" value="tocantins"> Tocantins

[2] Switch por grupo

Switch controla apenas interatividade. Marcação é preservada ao desabilitar e reabilitar.

Região Norte — ativa por padrão
Região Nordeste — inativa por padrão
<!-- Norte — ativo por padrão -->
<input type="checkbox" data-ozi-check-switch="norte" checked> Ativo/Inativo
<input type="checkbox" data-ozi-check-group="norte">          Selecionar todos

<input type="checkbox" data-ozi-check-item="norte" value="acre">  Acre
<input type="checkbox" data-ozi-check-item="norte" value="amapa"> Amapá

<!-- Nordeste — inativo por padrão -->
<input type="checkbox" data-ozi-check-switch="nordeste"> Ativo/Inativo
<input type="checkbox" data-ozi-check-group="nordeste">  Selecionar todos

<input type="checkbox" data-ozi-check-item="nordeste" value="alagoas"> Alagoas
<input type="checkbox" data-ozi-check-item="nordeste" value="bahia">   Bahia

[3] Switch multi-grupos (CSV)

Um único switch controla N grupos simultaneamente via valor CSV.

Grupo Norte
<div style="font-weight:500;font-size:12px;margin-bottom:4px;color:#666;">Região Norte</div>
<label style="display:flex;align-items:center;gap:6px;font-size:13px;margin-bottom:4px;">
    <input type="checkbox" data-ozi-check-group="demo3-norte"> Selecionar todos
</label>
<div style="margin-left:1.5rem;display:flex;flex-wrap:wrap;gap:4px 16px;margin-bottom:.75rem;">
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-norte" value="acre"> Acre</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-norte" value="amazonas"> Amazonas</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-norte" value="para"> Pará</label>
</div>

<div style="font-weight:500;font-size:12px;margin-bottom:4px;color:#666;">Região Nordeste</div>
<label style="display:flex;align-items:center;gap:6px;font-size:13px;margin-bottom:4px;">
    <input type="checkbox" data-ozi-check-group="demo3-nordeste"> Selecionar todos
</label>
<div style="margin-left:1.5rem;display:flex;flex-wrap:wrap;gap:4px 16px;margin-bottom:.75rem;">
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-nordeste" value="bahia"> Bahia</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-nordeste" value="ceara"> Ceará</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-nordeste" value="sergipe"> Sergipe</label>
</div>

<div style="font-weight:500;font-size:12px;margin-bottom:4px;color:#666;">Região Centro-Oeste</div>
<label style="display:flex;align-items:center;gap:6px;font-size:13px;margin-bottom:4px;">
    <input type="checkbox" data-ozi-check-group="demo3-centro-oeste"> Selecionar todos
</label>
<div style="margin-left:1.5rem;display:flex;flex-wrap:wrap;gap:4px 16px;">
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-centro-oeste" value="goias"> Goiás</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-centro-oeste" value="mato-grosso"> Mato Grosso</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-centro-oeste" value="df"> Distrito Federal</label>
</div>
Grupo Sul
<div style="font-weight:500;font-size:12px;margin-bottom:4px;color:#666;">Região Sudeste</div>
<label style="display:flex;align-items:center;gap:6px;font-size:13px;margin-bottom:4px;">
    <input type="checkbox" data-ozi-check-group="demo3-sudeste"> Selecionar todos
</label>
<div style="margin-left:1.5rem;display:flex;flex-wrap:wrap;gap:4px 16px;margin-bottom:.75rem;">
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-sudeste" value="sp"> São Paulo</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-sudeste" value="rj"> Rio de Janeiro</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-sudeste" value="mg"> Minas Gerais</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-sudeste" value="es"> Espírito Santo</label>
</div>

<div style="font-weight:500;font-size:12px;margin-bottom:4px;color:#666;">Região Sul</div>
<label style="display:flex;align-items:center;gap:6px;font-size:13px;margin-bottom:4px;">
    <input type="checkbox" data-ozi-check-group="demo3-sul"> Selecionar todos
</label>
<div style="margin-left:1.5rem;display:flex;flex-wrap:wrap;gap:4px 16px;">
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-sul" value="pr"> Paraná</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-sul" value="sc"> Santa Catarina</label>
    <label style="display:flex;align-items:center;gap:4px;font-size:13px;"><input type="checkbox" data-ozi-check-item="demo3-sul" value="rs"> Rio Grande do Sul</label>
</div>

<!-- switch CSV: controla nordeste, norte e centro-oeste -->
<input type="checkbox" data-ozi-check-switch="nordeste,norte,centro-oeste"> Gerencia os grupos

<input type="checkbox" data-ozi-check-group="norte"> Selecionar todos (Norte)
<input type="checkbox" data-ozi-check-item="norte" value="acre"> Acre

<input type="checkbox" data-ozi-check-group="nordeste"> Selecionar todos (Nordeste)
<input type="checkbox" data-ozi-check-item="nordeste" value="bahia"> Bahia

<input type="checkbox" data-ozi-check-group="centro-oeste"> Selecionar todos (Centro-Oeste)
<input type="checkbox" data-ozi-check-item="centro-oeste" value="goias"> Goiás

<!-- switch CSV: controla sudeste e sul — ativos por padrão -->
<input type="checkbox" data-ozi-check-switch="sudeste,sul" checked> Gerencia os grupos

<input type="checkbox" data-ozi-check-group="sudeste"> Selecionar todos (Sudeste)
<input type="checkbox" data-ozi-check-item="sudeste" value="sp"> São Paulo

<input type="checkbox" data-ozi-check-group="sul"> Selecionar todos (Sul)
<input type="checkbox" data-ozi-check-item="sul" value="pr"> Paraná

Recursos

  • Hierarquia em 3 níveis — switch → group → item
  • Controle de grupo — ativa ou desativa interatividade via switch, sem alterar marcação
  • Switch multi-grupo — um único switch controla N grupos via CSV
  • Marcar todos — marca ou desmarca todos os itens de uma vez via group
  • Sincronização automática — o group reflete sempre o estado real dos itens
  • Estado indeterminate — ativado automaticamente quando apenas parte dos itens está marcada
  • Preservação de estado — desabilitar e reabilitar um grupo mantém checked/indeterminate
  • Singleton puro — sem estado interno, lê o DOM a cada operação
  • Inicialização automática — inicia no DOMReady sem configuração manual
  • Suporte a conteúdo dinâmico — compatível com fetch e ZLD via refresh()
  • Múltiplos grupos — grupos completamente independentes na mesma página

Atributos HTML

Atributo Descrição Aceita CSV
data-ozi-check-switch="grupo" Ativa ou desativa 1 grupo. Controla apenas interatividade — não altera marcação. Sim
data-ozi-check-switch="g1,g2" Ativa ou desativa N grupos simultaneamente. Sim
data-ozi-check-group="grupo" Marca ou desmarca todos os itens. Estado tristate automático. Não
data-ozi-check-item="grupo" Checkbox individual do grupo. Não

Comportamento

Switch — ativo ou inativo

Estado do switch Efeito
Desligado group e todos os item ficam desabilitados. Marcação preservada.
Ligado Interatividade restaurada. syncGroup recalcula o tristate.
Ausente Grupo sempre ativo — isGroupEnabled retorna true.

Sincronização do group (tristate)

Estado dos itens Estado do data-ozi-check-group
Todos marcados checked = true, indeterminate = false
Nenhum marcado checked = false, indeterminate = false
Parte marcada checked = false, indeterminate = true
Nenhum item ativo checked = false, indeterminate = false

API Pública

Exposto em OZI.components.check e window.OziCheck.

Método Descrição
init() Bind de eventos + syncAllGroups(). Executado no DOMReady.
refresh(scope) Ressincroniza o escopo. Usar após fetch ou renderização Livewire.
getGroups(scope) Retorna array com todos os grupos únicos no escopo.
getGroupElements(group, scope) Retorna { $switch, $group, $items } para o grupo.
isGroupEnabled(group, scope) true se switch marcado ou ausente.
setGroupEnabledState(group, enabled, scope) Habilita ou desabilita grupo. Não altera marcação.
setAllItems(group, checked, scope) Marca ou desmarca todos os itens não-disabled.
syncGroup(group, scope) Recalcula e aplica tristate do group conforme itens.
syncAllGroups(scope) Sincroniza todos os grupos no escopo.

Exemplos de uso

// Habilitar/desabilitar grupo
OZI.components.check.setGroupEnabledState('modulos', true, document);
OZI.components.check.setGroupEnabledState('modulos', false, document);

// Marcar/desmarcar todos
OZI.components.check.setAllItems('modulos', true, document);
OZI.components.check.setAllItems('modulos', false, document);

// Sincronizar manualmente
OZI.components.check.syncGroup('modulos', document);

// Recarregar área específica — padrão IIFE do projeto
(function () {
    $('#destino').html(html);
    OZI.components.check.refresh($('#destino')[0]);
})();

Evento — ozi:check-change

Disparado em todos os pontos de mudança de estado via jQuery e CustomEvent nativo.

// CustomEvent nativo
document.addEventListener('ozi:check-change', function(e) {
    console.log(e.detail);
    // { group, source, enabled|checked|value }
});

// jQuery
$('[data-ozi-check-switch="modulos"]').on('ozi:check-change', function(e, payload) {
    console.log(payload.group, payload.source, payload.enabled);
});
payload.source Campos adicionais
'switch' group, enabled
'group' group, checked
'item' group, checked, value

Depreciados

Legado Substituto oficial
data-ozi-check-enabled data-ozi-check-switch
data-ozi-check-all data-ozi-check-group
oziCheckInitFetched(root) OZI.components.check.refresh()
$(document).trigger('oziCheck:initFetched') OZI.components.check.refresh()
© 2026 ozi-ui — Licenca MIT Laravel 13 · Livewire 3 · Bootstrap 5