Como corrigir o Gallery Field do ACF PRO quando o lightbox não funciona
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.
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.
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
- 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) - 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 - 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 - 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 - 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
<?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
Por que clicar na imagem do ACF Gallery não amplia nada
Como faço o link para a imagem em tamanho cheio no Gallery Field
O WP Rocket ou o lazy load podem quebrar o lightbox da galeria
Qual formato de retorno devo usar no Gallery Field para o lightbox
Como sei qual classe o meu lightbox espera nos links
O lightbox funciona em outras galerias mas não na do ACF, por quê
Como corrigir os Custom Post Types do JetEngine que não aparecem no frontend
CPT JetEngine que não aparece no frontend quase sempre vem de Public ou Has archive desligados no Post Type, ou de regras de reescrita desatualizadas. Marcar essas opções e regravar os permalinks resolve.
Como corrigir o Relationship Field no ACF PRO
O Relationship field do ACF PRO que não funciona acontece quando get_field() devolve um array inesperado, o loop com setup_postdata mostra o post errado por falta de wp_reset_postdata, ou a meta_query usa igualdade em vez de LIKE no valor serializado.
Como corrigir o layout quebrado de páginas de curso entre Tutor LMS e Astra Pro no WordPress
O layout quebrado entre Tutor LMS e Astra na página de curso ocorre quando o template de single course do Tutor entra em conflito com o container, a sidebar ou a largura de conteúdo definidos pelo tema Astra, deixando a página desalinhada, com sidebar indevida ou sobreposta ao cabeçalho.
Como corrigir o erro de query no Listing Grid do JetEngine
O erro de query no Listing Grid do JetEngine ocorre quando a Custom Query do Query Builder falha ou não retorna nada: tipo de query trocado, SQL invalido, meta query que exclui todos os registros ou macro vazia. O grid fica vazio ou exibe aviso de banco enquanto o Preview do Query Builder parece correto.
Como corrigir o erro do Image Grid no Happy Addons
O erro do Image Grid no Happy Addons acontece quando o widget está desativado no Feature Controller, o Elementor está desatualizado ou um cache antigo serve o CSS e o JavaScript errados, fazendo o widget sumir do editor, as imagens não aparecerem ou o layout masonry quebrar.
Como corrigir o layout quebrado entre Astra Pro e Crocoblock JetEngine no WordPress
O layout quebrado entre Astra Pro e Crocoblock JetEngine ocorre quando a largura de conteúdo e o sidebar definidos pelo Astra entram em conflito com a estrutura que o JetEngine usa para renderizar Listing Grids e templates dinâmicos, fazendo o conteúdo estourar ou encolher na página.
Saúde e Bem-Estar
Restaurantes & Alimentação
Hotelaria & Turismo
Imobiliárias & Construção
Negócios Locais & Franquias
E-commerce & Lojas Virtuais
Educação & Cursos
Profissionais Liberais & Serviços
Agências Digitais & Freelancers
MEIs e Autônomos
Agências e Freelancers
Pequenas Empresas
Startups
Franquias
Elementor PRO
Rank Math
SEOPress
Happy Addons
Tutor LMS
WP Optimize
Crocoblock
WP Rocket
Ultimate Addons
Perfmatter
Funnel Kit
AIOS
Astra PRO
ACF
Essential Addons
WP Forms
UpdraftPlus
Ver mais
FULL CRM 
FULL Widget
FULL Woo
FULL Pop-up
FULL Security
FULL NPS
FULL Update
FULL Social Proof
FULL Analytics
FULL Templates
FULL Creator AI
FULL Backup
FULL Safe Login
FULL SMTP
FULL Monitor
FULL Speed
FULL Cache
FULL Whitelabel
