# Como corrigir o Gallery Field do ACF PRO quando o lightbox não funciona

O lightbox do Gallery Field do ACF PRO não funciona porque o ACF não inclui lightbox próprio: ele só entrega os dados das imagens, e o efeito de ampliar ao clicar depende de o seu template renderizar o link para a imagem cheia com o atributo que a biblioteca de lightbox do tema ou plugin reconhece.

## O que é lightbox do Gallery Field do ACF PRO?

O Gallery Field do ACF PRO é um campo que armazena uma coleção de imagens da Biblioteca de Mídia e, ao ser consultado no template com get_field, devolve um array de anexos conforme o formato de retorno configurado (Array, URL ou ID). Cada item em formato Array traz subcampos como url, sizes, alt e caption. Segundo a documentação oficial do ACF, o campo cuida apenas dos dados e do gerenciamento das imagens no painel; ele não inclui nenhuma funcionalidade de lightbox no frontend.

O lightbox do Gallery Field do ACF PRO depende, portanto, de uma biblioteca externa de lightbox que vem do tema ou de outro plugin (por exemplo, o lightbox de um page builder, um plugin de galeria ou uma lib como a do bloco nativo de imagem). Essa biblioteca só amplia a imagem ao clique quando o HTML renderizado pelo seu loop expõe um link para o arquivo original e, em muitos casos, uma classe ou atributo que ela escuta. Quando o template do desenvolvedor imprime apenas a tag img sem esse link, ou quando um plugin de lazy load reescreve a marcação antes da lib inicializar, o clique não amplia nada e o lightbox parece quebrado.

## Como identificar

- Ao clicar em uma imagem do Gallery Field, nada acontece: a imagem não amplia e nenhuma janela de lightbox abre.
- O clique abre o arquivo da imagem em uma aba ou página em branco, em vez de exibir o overlay do lightbox.
- O lightbox funciona nas galerias nativas do tema ou do page builder, mas não nas imagens renderizadas pelo Gallery Field do ACF.
- No console do navegador aparece um aviso de seletor não encontrado ou a biblioteca de lightbox não registra nenhum item para inicializar.
- As imagens do ACF aparecem com o atributo data-src de lazy load e sem o link para o arquivo original, então a lib de lightbox não tem o que abrir.

**Antes de começar:** Antes de editar o template do tema ou mexer no plugin de lazy load em produção, faça um backup do site (arquivos e banco de dados) ou teste primeiro em um ambiente de staging, para poder reverter caso a renderização da galeria quebre.

## Como prevenir

- Padronize um template part reutilizável para galerias do ACF que sempre envolva a miniatura em um link para a imagem cheia com a classe correta do lightbox.
- Documente qual biblioteca de lightbox o site usa e qual classe ou atributo data ela exige, para que todo novo template já saia compatível.
- Mantenha o Gallery Field sempre com formato de retorno Array ou URL nos grupos de campos, evitando o formato ID que dificulta montar o link da imagem original.
- Ao configurar lazy load ou otimização, valide as galerias do ACF em staging para garantir que a reescrita de markup não quebre a inicialização do lightbox.

Erros relacionados

- [Como corrigir o Gallery Field com imagens que não carregam no ACF PRO](https://full.services/wp-fixer/corrigir-gallery-field-imagens-acf-pro/)
- [Como corrigir Custom Fields que não aparecem no frontend no ACF PRO](https://full.services/wp-fixer/corrigir-custom-fields-frontend-acf-pro/)
- [Como corrigir o Flexible Content do ACF PRO que não renderiza no Elementor](https://full.services/wp-fixer/corrigir-flexible-content-elementor-acf-pro/)

## Causa

- O template imprime apenas a tag img do Gallery Field sem envolvê-la em um link para a imagem em tamanho cheio; sem esse href para o arquivo original, a biblioteca de lightbox não tem o alvo para ampliar.
- O loop usa o subcampo de miniatura (image['sizes']['thumbnail']) tanto na img quanto no link, então o lightbox abre a versão pequena e o efeito parece não funcionar em vez de exibir a imagem cheia.
- A biblioteca de lightbox do tema ou plugin escuta uma classe ou atributo data específico (por exemplo data-fancybox ou uma classe de galeria) que o HTML manual do ACF não inclui, então ela ignora os links e não inicializa nenhum item.
- Um plugin de lazy load ou otimização (como o WP Rocket) reescreve o atributo src para data-src e adia o carregamento, e a lib de lightbox lê o markup antes da troca, encontrando imagens sem o caminho original para abrir.
- O formato de retorno do campo está como ID em vez de Array ou URL, então o template recebe só números de anexo e o desenvolvedor não consegue montar o href para o arquivo original que o lightbox precisa.

## Como resolver

1. Confirme o formato de retorno do Gallery Field: Em ACF, abra o grupo de campos e o Gallery Field e confirme que o formato de retorno é Array ou URL, não ID. O formato Array entrega url, sizes, alt e caption, que você precisa para montar a miniatura e o link da imagem cheia que o lightbox vai abrir.

```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo
Abra o Gallery Field e ajuste 'Formato de Retorno' para Array (ou URL)
```

2. Renderize cada imagem dentro de um link para o arquivo cheio: No template, percorra o array do get_field e, para cada imagem, gere um link (a) cujo href aponta para o url da imagem original e, dentro dele, a miniatura. Sem esse link para o arquivo cheio o lightbox não tem o que ampliar, pois o ACF não fornece lightbox próprio segundo a documentação oficial.

```
Edite o arquivo de template do tema (ex.: single.php ou um template part)
Use get_field('galeria') e percorra o array de imagens
Em cada item, monte um link a com href no url da imagem cheia e a miniatura dentro dele
```

3. Adicione a classe ou o atributo que o seu lightbox escuta: Descubra qual seletor a biblioteca de lightbox do tema ou plugin usa para se ativar e inclua essa classe ou atributo data no link de cada imagem. Sem o seletor correto a lib ignora os links do ACF e não abre nada ao clique.

```
Verifique na doc do tema/plugin de lightbox qual classe ou data-atributo ele exige
Adicione esse seletor ao link de cada imagem (ex.: class ou data-* no elemento a)
Use o mesmo identificador de grupo nos links para a galeria navegar entre imagens
```

4. Trate o lazy load que reescreve o markup: Se um plugin de lazy load ou otimização troca o src por data-src antes do lightbox inicializar, exclua as imagens do Gallery Field do lazy load ou garanta que o link (href) para o arquivo cheio não seja afetado, pois o lightbox abre o href, não o src.

```
No plugin de cache/otimização, exclua as imagens da galeria do lazy load
Confirme que o href do link aponta para o arquivo original e não para data-src
Limpe o cache e recarregue a página para testar o clique
```

5. Isole conflito de JavaScript e reteste: Se o lightbox ainda não abre, abra o console do navegador para ver se a biblioteca carregou e se encontrou os itens, e desative outros plugins um a um para identificar um conflito de JavaScript que impeça a lib de inicializar sobre o markup do ACF.

```
Abra o console (F12 -> Console) e recarregue a página com a galeria
Verifique se a lib de lightbox carregou e quantos itens ela registrou
Desative os demais plugins um a um, recarregando a cada teste, até achar o conflito
```


## Código

```php
<?php
// Renderiza o Gallery Field do ACF com link para a imagem cheia + classe de lightbox.
$imagens = get_field( 'galeria' ); // Formato de retorno: Array
if ( $imagens ) : ?>
    <div class="acf-galeria">
        <?php foreach ( $imagens as $imagem ) :
            $cheia = esc_url( $imagem['url'] );
            $thumb = esc_url( $imagem['sizes']['medium'] );
            $alt   = esc_attr( $imagem['alt'] ); ?>
            <a href="<?php echo $cheia; ?>"
               class="lightbox"
               data-fancybox="galeria-acf">
                <img src="<?php echo $thumb; ?>" alt="<?php echo $alt; ?>">
            </a>
        <?php endforeach; ?>
    </div>
<?php endif;
```

## Perguntas frequentes

### O ACF PRO tem lightbox próprio para o Gallery Field

Não. A documentação oficial do ACF deixa claro que o Gallery Field cuida apenas dos dados e do gerenciamento das imagens; ele não inclui lightbox no frontend. O efeito de ampliar ao clicar vem de uma biblioteca do tema ou de outro plugin que você aplica ao markup renderizado.

### Por que clicar na imagem do ACF Gallery não amplia nada

Em geral o template imprime só a tag img sem um link para o arquivo cheio, então a biblioteca de lightbox não tem o que abrir. Envolva cada imagem em um link cujo href aponta para a url da imagem original e adicione a classe que o lightbox escuta.

### Como faço o link para a imagem em tamanho cheio no Gallery Field

Use o formato de retorno Array no campo e, no loop, pegue o subcampo url de cada imagem para o href do link e um tamanho menor de sizes para a miniatura. Assim o lightbox abre o arquivo original enquanto a página exibe a versão reduzida.

### O WP Rocket ou o lazy load podem quebrar o lightbox da galeria

Sim. Plugins de lazy load reescrevem o src da imagem para data-src e adiam o carregamento, e a lib de lightbox pode ler o markup antes da troca. Exclua as imagens da galeria do lazy load ou garanta que o href do link para o arquivo cheio não seja afetado.

### Qual formato de retorno devo usar no Gallery Field para o lightbox

Use Array ou URL. O formato Array entrega url, sizes, alt e caption de cada imagem, o que permite montar a miniatura e o link da imagem cheia. O formato ID devolve apenas números de anexo e dificulta gerar o href que o lightbox precisa.

### Como sei qual classe o meu lightbox espera nos links

Consulte a documentação do tema ou do plugin de lightbox que você usa; cada um escuta uma classe ou um atributo data específico, como uma classe de galeria ou um data-atributo. Adicione esse seletor ao link de cada imagem do ACF para a lib inicializar.

### O lightbox funciona em outras galerias mas não na do ACF, por quê

Porque as outras galerias já saem com o markup que a lib espera, e a do ACF é renderizada manualmente pelo seu template. Replique no loop do ACF a mesma estrutura de link e classe das galerias que funcionam para o lightbox reconhecer as imagens.

**Fonte:** [Advanced Custom Fields — Gallery Field](https://www.advancedcustomfields.com/resources/gallery/)