# Como corrigir o Color Picker que não aplica a cor no frontend no ACF PRO

O ACF color picker não aplica cor no frontend quando o template não imprime o valor do campo, quando o nome do campo está errado ou quando a transparência muda o retorno para RGBA e o código espera HEX. O Color Picker do ACF PRO guarda a cor, mas só aparece se o tema a imprimir no HTML ou no CSS.

## O que é Color Picker que não aplica a cor no ACF PRO?

O ACF color picker é o campo que guarda uma cor escolhida no editor para você reutilizar no layout. Segundo a documentação oficial do ACF, o campo retorna por padrão uma string com o valor HEX, incluindo o prefixo cerquilha, por exemplo o código de uma cor sólida. Quando a opção de transparência está ligada, o retorno passa a ser uma string RGBA ou um array RGBA, conforme o formato de retorno configurado no campo.

O ponto central é que o ACF apenas armazena e devolve esse valor: ele não pinta nada sozinho no frontend. A cor só aparece quando o template do tema lê o campo com get_field ou the_field e injeta o valor em um atributo style inline ou em uma regra de CSS. Se o template não imprime o valor, se o nome do campo passado não bate com o registrado, ou se o código monta um style esperando HEX enquanto a transparência devolve RGBA, a cor escolhida fica salva mas nunca chega ao visitante.

## Como identificar

- A cor é salva no editor e reaparece corretamente no painel do ACF, mas o elemento no frontend continua com a cor padrão do tema.
- O bloco de style impresso no HTML sai vazio, como 'style="background-color:"', sem nenhum valor de cor depois dos dois pontos.
- Ao inspecionar o elemento, a propriedade background-color ou color simplesmente não existe na regra, como se o campo nunca tivesse sido lido.
- Com a transparência ligada, aparece o aviso de array no template, do tipo 'Array to string conversion', porque o código tenta imprimir um array RGBA como texto.
- A cor funciona em uma página mas some em outra (arquivo, single ou Options Page), indicando que o get_field foi chamado sem o ID de post correto.

**Antes de começar:** Antes de editar arquivos de template do tema, use um tema filho e faça backup do site (arquivos e banco de dados) ou teste em um ambiente de staging, para poder reverter caso a edição quebre a página.

## Como prevenir

- Sempre use o Field Name exato do ACF em get_field e the_field, copiado direto do grupo de campos, para evitar retorno vazio por digitação.
- Defina e documente o Return Format do Color Picker (HEX ou RGBA) por campo, e escreva o template já tratando o formato escolhido.
- Escape e valide o valor antes de imprimir no atributo style, usando esc_attr, para impedir que um valor inesperado quebre o HTML.
- Em Options Page e templates globais, sempre passe o ID do post ou 'option' no get_field para ler o contexto certo.
- Inclua um teste visual em janela anônima após publicar, com o cache limpo, para confirmar que a cor chega ao visitante final.

Erros relacionados

- [Como corrigir o Image Field no ACF PRO](https://full.services/wp-fixer/corrigir-image-field-acf-pro/)
- [Como corrigir o Google Maps Field no ACF PRO (chave de API)](https://full.services/wp-fixer/corrigir-google-maps-field-acf-pro/)
- [Como corrigir o WYSIWYG Editor que não carrega no ACF PRO](https://full.services/wp-fixer/corrigir-wysiwyg-editor-acf-pro/)

## Causa

- O template do tema não imprime o valor do campo: a cor é salva pelo ACF mas nenhum get_field ou the_field injeta o valor HEX em um atributo style ou regra de CSS, então o frontend nunca recebe a cor.
- O nome do campo passado para get_field não corresponde ao name registrado no grupo de campos (erro de digitação ou uso do label em vez do name), fazendo a função retornar vazio e o style sair sem cor.
- A opção Enable Transparency está ligada e o formato de retorno virou string ou array RGBA, mas o código do template foi escrito esperando a string HEX padrão, quebrando a montagem do valor no CSS.
- O get_field é chamado fora do loop ou em um contexto sem o post correto (Options Page, arquivo ou template global) sem informar o ID do post ou a string 'option', então o ACF lê um post errado e devolve vazio.
- Um plugin de cache de página ou de minificação de CSS serve uma versão antiga sem o style inline recém-impresso, mantendo no visitante a cor anterior mesmo após o template já imprimir o novo valor.

## Como resolver

1. Confirme o name exato do campo no grupo de campos: Em ACF, Grupos de Campos, abra o grupo e copie o Field Name (não o Label) do Color Picker. É esse name que você passa para get_field ou the_field. Um label com espaços ou maiúsculas no lugar do name faz a função retornar vazio.

```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo do Color Picker
Copie o valor do campo 'Field Name' (ex.: cor_destaque)
```

2. Imprima o valor do campo no template do tema: Edite o arquivo de template do tema (via editor de tema filho ou FTP) e use the_field ou get_field para injetar a cor em um atributo style inline, exatamente como mostra a documentação do ACF. Sem essa impressão o ACF nunca aplica a cor no frontend. O bloco de código abaixo traz o exemplo seguro e completo.

```
Abra o template do tema filho (ex.: single.php ou o template do bloco)
Use the_field('cor_destaque') dentro do atributo style do elemento
Salve e recarregue a página no frontend
```

3. Trate o formato de retorno quando a transparência está ligada: Se você ativou Enable Transparency, o campo pode devolver uma string RGBA ou um array RGBA em vez do HEX. Verifique a configuração Return Format do campo e, no template, use a string RGBA diretamente; se o retorno for array, monte a string rgba() a partir das chaves antes de imprimir.

```
Painel WP -> ACF -> abra o campo Color Picker -> confira 'Return Format'
Use 'String' para imprimir o valor direto no CSS, ou trate o array no PHP
```

4. Garanta o contexto de post correto fora do loop: Em Options Page ou em templates fora do loop, passe o segundo argumento de get_field com o ID do post ou a string option, senão o ACF lê o post errado e devolve vazio. Use o get_field com o alvo explícito e só então imprima a cor.

```
Para Options Page: get_field('cor_destaque', 'option')
Para um post específico: get_field('cor_destaque', $post_id)
```

5. Limpe o cache de página e de CSS: Depois de corrigir o template, limpe o cache do plugin de cache e do CDN para que o visitante receba o style inline atualizado. Cache antigo é a causa de a cor já aparecer pra você logado e não pro visitante anônimo.

```
Painel WP -> plugin de cache -> Limpar todo o cache
Limpe também o cache do CDN/Cloudflare se houver
Abra a página em janela anônima para confirmar a cor
```


## Código

```php
<?php
// Exibe a cor do Color Picker do ACF PRO no frontend com seguranca.
$cor = get_field( 'cor_destaque' ); // use 'option' como 2o arg em Options Page

if ( $cor ) {
    if ( is_array( $cor ) ) {
        // Transparencia com Return Format = Array: monta a string rgba().
        $cor = sprintf(
            'rgba(%d, %d, %d, %s)',
            $cor['red'],
            $cor['green'],
            $cor['blue'],
            $cor['alpha']
        );
    }
    printf(
        '<div class="destaque" style="background-color: %s;">conteudo</div>',
        esc_attr( $cor )
    );
}
```

## Perguntas frequentes

### Por que o Color Picker do ACF salva a cor mas ela não aparece no site

Porque o ACF apenas guarda e devolve o valor; ele não pinta nada sozinho. A cor só aparece quando o template do tema lê o campo com get_field ou the_field e imprime o valor em um atributo style inline ou em uma regra de CSS. Sem essa impressão, a cor fica salva mas nunca chega ao frontend.

### Qual valor o Color Picker do ACF PRO retorna

Segundo a documentação oficial do ACF, o campo retorna por padrão uma string com o valor HEX incluindo o prefixo cerquilha. Quando a opção de transparência está ligada, o retorno passa a ser uma string RGBA ou um array RGBA, conforme o Return Format configurado no campo.

### Como exibo a cor do Color Picker dentro de um style inline

Use the_field com o name do campo dentro do atributo style, por exemplo aplicando background-color com o valor impresso pela função. A documentação do ACF mostra exatamente esse padrão, injetando a string HEX direto no atributo style do elemento.

### Por que aparece o aviso Array to string conversion no template do Color Picker

Esse aviso surge quando a transparência está ligada e o Return Format devolve um array RGBA, mas o código tenta imprimir esse array como texto. Troque o Return Format para String, ou monte a string rgba a partir das chaves do array antes de imprimir no CSS.

### Por que a cor some quando uso o campo em uma Options Page

Porque fora do loop o get_field não sabe de qual post ler. Em Options Page você precisa passar a string option como segundo argumento, por exemplo get_field com 'option', para o ACF buscar o valor salvo nas opções e devolver a cor correta.

### A cor aparece pra mim logado mas não pro visitante, o que é

Quase sempre é cache. Um plugin de cache de página ou o CDN serve uma versão antiga sem o style inline novo. Limpe o cache do plugin e do CDN e confirme em uma janela anônima para garantir que o visitante recebe a cor atualizada.

### Preciso escapar o valor do Color Picker antes de imprimir no HTML

Sim. Mesmo que o valor venha do seu próprio campo, passe-o por esc_attr antes de colocá-lo no atributo style. Isso evita que um valor inesperado quebre o HTML e mantém o código seguro ao montar o estilo a partir do campo.

**Fonte:** [Advanced Custom Fields — Color Picker field](https://www.advancedcustomfields.com/resources/color-picker/)