Construir um painel de definições personalizado para um tema WordPress é uma tarefa que pode prolongar-se por semanas. A API de Definições do WordPress exige a escrita de imenso código repetitivo: registo, renderização de campos, validação, gravação. E quando o projeto está a arder, escrever tudo isto de raiz é um luxo injustificável.

O Redux Framework resolve este problema de forma radical: em vez da complicação manual com a API de Definições, descreve os campos necessários num ficheiro de configuração, e o framework trata de tudo o resto, renderização, validação, escape, importação/exportação e até CSS dinâmico. No WordPress.org, o plugin tem mais de 32 milhões de downloads e mais de um milhão de instalações ativas, e isto não é inflação de marketing, mas uma consequência direta do facto de o Redux poupar realmente semanas de desenvolvimento.

Neste guia, configuração passo a passo do Redux Framework, do zero até um painel de opções de tema funcional, incluindo demonstração ao vivo no personalizador e utilização segura dos valores guardados no frontend.

💡 Visão geral rápida:

• Instalar o Redux Framework: três formas de integrar num projeto WordPress
• Ligar o framework e criar um ficheiro de configuração
• Configurar os argumentos do painel: posição no menu, personalizador, Google Fonts
• Adicionar secções e campos de entrada através da API unificada do Redux
• Extrair valores guardados nos templates do tema com proteção contra erros

O que é o Redux Framework e porque precisa dele

O Redux Framework é um framework de opções gratuito e de código aberto para temas e plugins WordPress. É construído sobre a API de Definições padrão do WordPress, mas abstrai completamente a sua complexidade. Em vez de dezenas de chamadas a register_setting, add_settings_field e settings_fields, escreve um array declarativo em PHP e obtém um painel de definições totalmente funcional e responsivo, com 49 tipos de campo à escolha.

É importante não confundir com a biblioteca JavaScript Redux para gestão de estado, são produtos completamente diferentes com o mesmo nome. O framework WordPress surgiu antes da biblioteca JS.

Principais capacidades que obtém «out of the box»:

• 49 tipos de campo: desde texto simples e checkbox até editor ACE, repetidor, Google Maps, ordenador de blocos e slider de imagens;
• Saída automática de CSS: para campos de tipografia, cor, gradiente, espaçamento, basta especificar um seletor CSS e o próprio Redux gera uma folha de estilos com Google Fonts;
• Integração com o personalizador: o mesmo argumento customizer => true, e todo o painel é duplicado no Personalizador do WordPress com pré-visualização ao vivo;
• Importar/exportar definições: ferramenta incorporada para transferir a configuração entre sites;
• Compilador: um hook que é acionado quando um campo com a flag compile => true muda, pode, por exemplo, recompilar SCSS;
• Validação e escape: cada valor passa por uma sanitização correspondente ao tipo de campo, um campo de texto não aceita um array, um numérico filtra strings.

Desde 2024, o framework tem sido desenvolvido sob a alçada da Team Updraft (David Anderson, criador do UpdraftPlus). Versão atual, 4.5.11 (março de 2026), compatibilidade total com WordPress 7.0 e PHP 8.5. O projeto está em redux.io, a documentação no site de documentação do Redux.

Instalar o Redux Framework

Há três formas de adicionar o Redux a um projeto. A escolha depende da arquitetura do seu tema e de como planeia distribuí-lo.

Como um plugin separado

Instale o Redux Framework a partir do diretório do WordPress.org como um plugin normal. Após a ativação, o painel de opções não aparece, o plugin apenas fornece a API. Descreve todas as definições num ficheiro de configuração dentro do seu tema.

Vantagens: o tema permanece leve (o núcleo do framework não incha o arquivo); o framework atualiza-se independentemente através do mecanismo padrão do WordPress.

Desvantagens: o seu tema requer a presença de um plugin de terceiros, o utilizador precisa de o instalar e ativar separadamente; sem o plugin, o painel de definições desaparece e precisa de fornecer um fallback gracioso no código do tema.

No núcleo do tema

Copie a pasta ReduxCore para dentro do seu tema e ligue-a no functions.php. O framework torna-se parte integrante do tema, o utilizador não precisa de instalar um plugin adicional.

Vantagens: o painel de definições parece uma parte nativa do tema, o utilizador não instala nada adicional.

Desvantagens: o tamanho do arquivo do tema aumenta cerca de 2 MB; cada atualização do framework exige uma atualização do tema da sua parte; o plugin Theme Check pode emitir avisos.

Num plugin de tema dependente

Abordagem recomendada para temas premium. Crie um plugin complementar separado para o seu tema (também é conveniente para manter tipos de post personalizados, shortcodes, widgets) e incorpore o Redux nele. No functions.php do tema, adicione uma verificação da presença deste plugin através do TGMPA ou de um mecanismo semelhante.

Vantagens: arquitetura limpa (a funcionalidade do tema está separada da apresentação); o framework não incha o arquivo do tema; as atualizações do framework não afetam diretamente o código do tema.

Desvantagens: exige escrever e manter um plugin separado; barreira de entrada ligeiramente mais alta para outros developers que vão analisar o projeto.

A configuração do Redux não depende do método de instalação, os passos seguintes são idênticos para qualquer variante.

Configuração geral: ligar o framework

Dentro do plugin Redux Framework (ou do arquivo descarregado do site oficial do Redux) encontre a pasta ReduxCore, ela contém todo o núcleo.

Crie uma pasta no seu plugin (ou tema), por exemplo optionpanel, e copie o conteúdo de ReduxCore para lá. Coloque um ficheiro config.php vazio ao lado, vamos descrever todas as secções e campos do painel nele.

Agora ligue o framework. No ficheiro principal do plugin (ou no functions.php do tema) adicione:

1
<?php
2
if ( ! class_exists( 'Redux' ) ) {
3
    require_once plugin_dir_path( __FILE__ ) . 'optionpanel/ReduxCore/framework.php';
4
}

A verificação class_exists impede um erro fatal se outra parte do site já tiver carregado o Redux (por exemplo, através de um plugin separado). Se o framework estiver ausente, o painel de configurações simplesmente não carrega e o site continua a funcionar.

Depois disto, pode avançar para a criação de secções e campos.

Criação do painel de opções

Argumentos do framework

Primeiro, defina uma variável global para armazenar todas as configurações; ela será necessária para extrair os valores nos templates do tema:

1
$opt_name = 'mytheme_options';

O prefixo é obrigatório e evita conflitos de nomes com outros plugins que usam o Redux. Boa prática: brandname_themename.

Agora vamos montar o array de argumentos. Aqui está uma configuração mínima funcional:

1
$args = array(
2
    'opt_name'             => $opt_name,
3
    'display_name'         => 'Theme Settings',
4
    'display_version'      => '1.0.0',
5
    'menu_type'            => 'submenu',
6
    'allow_sub_menu'       => true,
7
    'menu_title'           => 'Theme Settings',
8
    'page_title'           => 'Theme Settings Panel',
9
    'page_parent'          => 'themes.php',
10
    'page_permissions'     => 'manage_options',
11
    'page_slug'            => 'theme_options',
12
    'dev_mode'             => false,
13
    'update_notice'        => false,
14
    'customizer'           => true,
15
    'save_defaults'        => true,
16
    'show_import_export'   => true,
17
    'async_typography'     => true,
18
    'admin_bar'            => true,
19
    'global_variable'      => $opt_name,
20
);
21
 
22
Redux::set_args( $opt_name, $args );

Descrição dos argumentos principais:

• menu_type: submenu, o painel aparece dentro do item de menu «Aparência»; menu, item de topo separado na administração;
• customizer: true ativa a duplicação de todos os campos no Personalizador do WordPress com pré-visualização ao vivo, o utilizador vê as alterações antes de guardar;
• dev_mode: ative durante o desenvolvimento (depuração alargada, importação de demonstração), mas desligue definitivamente antes do lançamento;
• update_notice: sempre false para temas e plugins com Redux incorporado; os seus utilizadores não devem receber notificações sobre atualizações do framework separadamente do seu produto;
• show_import_export: adiciona uma ferramenta para transferir todas as configurações entre sites com um clique.

Consulte a lista completa com mais de 40 argumentos no guia de argumentos.

Adicionar secções e campos

Uma secção é um grupo lógico de campos (separador no ecrã de configurações). Secção mínima:

1
Redux::set_section( $opt_name, array(
2
    'title'  => 'Site Header',
3
    'id'     => 'header_section',
4
    'icon'   => 'dashicons-heading',
5
    'fields' => array(
6
        array(
7
            'id'       => 'header_logo',
8
            'type'     => 'media',
9
            'title'    => 'Logo',
10
            'subtitle' => 'Upload logo image',
11
            'default'  => array( 'url' => get_template_directory_uri() . '/images/logo.png' ),
12
        ),
13
        array(
14
            'id'      => 'sticky_header',
15
            'type'    => 'switch',
16
            'title'   => 'Sticky Header',
17
            'default' => true,
18
        ),
19
    ),
20
) );

Ícones das secções: o Redux 4.x suporta os Dashicons nativos do WordPress (lista completa em developer.wordpress.org). Para ícones personalizados, use classes CSS do seu conjunto de ícones (por exemplo, Font Awesome).

Cada campo é um array associativo com as chaves obrigatórias id, type e title. Exemplos de tipos frequentemente utilizados:

1
// Select with search
2
array(
3
    'id'      => 'sidebar_layout',
4
    'type'    => 'select',
5
    'title'   => 'Sidebar Layout',
6
    'options' => array(
7
        'right' => 'Sidebar Right',
8
        'left'  => 'Sidebar Left',
9
        'none'  => 'No Sidebar',
10
    ),
11
    'default' => 'right',
12
),
13
 
14
// RGBA color picker
15
array(
16
    'id'      => 'accent_color',
17
    'type'    => 'color_rgba',
18
    'title'   => 'Accent Color',
19
    'default' => array(
20
        'color' => '#2271b1',
21
        'alpha' => 1,
22
    ),
23
),
24
 
25
// Typography with Google Fonts
26
array(
27
    'id'          => 'body_typography',
28
    'type'        => 'typography',
29
    'title'       => 'Text Font',
30
    'google'      => true,
31
    'font-backup' => true,
32
    'line-height' => true,
33
    'font-size'   => true,
34
    'default'     => array(
35
        'font-family' => 'Inter',
36
        'font-size'   => '16px',
37
    ),
38
),

Para criar uma subsecção, adicione o argumento 'subsection' => true; o campo aparecerá como um separador aninhado dentro da secção principal.

Lista de todos os 49 tipos com exemplos de configuração na secção de tipos de campos da documentação do Redux.

Utilizar opções no tema

O Redux armazena todos os valores numa variável global, a mesma que especificou em $opt_name. Para obter um valor num template, primeiro declare-a como global. Mas a declaração direta de global fora de uma função ou ação é má prática. A abordagem correta:

1
function mytheme_get_option( $option_id, $default = '' ) {
2
    global $mytheme_options;
3
    return isset( $mytheme_options[ $option_id ] ) ? $mytheme_options[ $option_id ] : $default;
4
}

A função de invólucro faz duas coisas: evita o aviso PHP «undefined index» ao aceder a uma chave inexistente e fornece um valor de fallback. No template, a utilização tem este aspeto:

1
$logo = mytheme_get_option( 'header_logo' );
2
if ( ! empty( $logo['url'] ) ) {
3
    echo '<img src="' . esc_url( $logo['url'] ) . '" alt="' . esc_attr( get_bloginfo( 'name' ) ) . '">';
4
}

Se o painel de definições ainda não estiver configurado (por exemplo, o utilizador ativou o tema mas não instalou o plugin dependente), $mytheme_options será um array vazio e mytheme_get_option() devolverá silenciosamente $default, sem um monte de avisos no debug.log.

Para CSS dinâmico, utilize a capacidade incorporada do Redux, especifique o argumento output na configuração do campo:

1
array(
2
    'id'     => 'body_bg_color',
3
    'type'   => 'color',
4
    'title'  => 'Background Color',
5
    'output' => array( 'background-color' => 'body' ),
6
),

O Redux irá gerar e incorporar automaticamente a regra CSS <style>body{background-color:#fff;}</style>, sem uma única linha de código manual.

O processo de instalação e configuração de campos é mostrado claramente neste tutorial em vídeo: desde ligar a framework até criar a primeira secção com selects e switches:

⁉️🤔 Perguntas frequentes

Em que é que o Redux Framework difere do Carbon Fields, ACF Options Pages e outras soluções?

O Redux oferece 49 tipos de campo «prontos a usar» (contra ~25 do Carbon Fields e ~30 do ACF Pro) e foca-se especificamente em painéis de definições de temas, não em campos de metadados de posts. O ACF Options Pages é um complemento sobre o motor de metacampos, enquanto o Redux foi originalmente concebido para painéis de opções: importação/exportação incorporada, compilador, pré-visualização ao vivo no personalizador, CSS dinâmico com Google Fonts. O Carbon Fields está mais próximo em espírito, mas requer Composer e namespaces, o que em vários ambientes de alojamento é uma barreira. Conclusão: se já usa ACF para metacampos, opte pelo ACF Options Pages para evitar multiplicar entidades; se está a construir um tema de raiz e precisa de um painel de opções potente, o Redux dar-lhe-á mais funcionalidades gratuitamente.

O Redux Framework funciona com temas de blocos (Full Site Editing)?

Sim, mas com ressalvas. O Redux produz o painel de definições através da interface clássica de administração (Settings API), não através do editor do site. Para uma abordagem híbrida, tema de blocos mais painel Redux para definições globais (cores, tipografia, scripts de analytics), a combinação funciona. A partir da versão 4.5.11, a integração direta com theme.json não está implementada: os valores precisam de ser extraídos nos templates através de mytheme_get_option() e inseridos como variáveis CSS. Para um ambiente FSE puro, onde todas as definições devem residir no editor do site, o Redux é redundante; para temas clássicos e híbridos, é uma das melhores opções.

O que fazer se o Redux entrar em conflito com outro plugin que use esta mesma biblioteca?

Este é um problema conhecido de «inclusão dupla». A verificação if ( ! class_exists( 'Redux' ) ) antes de require_once garante que a framework será carregada exatamente uma vez: o WordPress executa PHP sequencialmente e o primeiro require_once torna as chamadas subsequentes inofensivas. Se o seu tema e um plugin de terceiros ambos incluírem o Redux, a cópia que inicializou primeiro será carregada e os painéis de ambos os produtos continuarão a funcionar. Com uma diferença significativa nas versões principais, é possível haver incompatibilidade ao nível da API, corrigida atualizando o lado desatualizado para a versão atual.

É necessária uma licença para usar o Redux Framework num tema comercial?

Não. O Redux é distribuído sob GPLv2, a mesma licença do WordPress. Pode incluir livremente a framework em temas e plugins comerciais, vendê-los no ThemeForest, distribuí-los através do seu próprio site. A única restrição GPLv2, obras derivadas devem também estar sob GPLv2, mas este requisito aplica-se ao código-fonte, não ao conteúdo do site do utilizador final. O Redux Pro (campos adicionais, personalizador estendido, suporte prioritário) é um produto pago separado, não necessário para o funcionamento da framework.

O que fazer se, após uma atualização do WordPress, o painel do Redux deixar de abrir?

Cenário: após uma atualização principal do WP, ecrã branco na página de definições do tema. Ordem de ações: primeiro, verifique se tem a versão do Redux não inferior a 4.5.11 (compatibilidade com WP 7.0). Segundo, durante um minuto, ative 'dev_mode' => true e veja a saída de erros PHP no ecrã de definições; o Redux em modo dev mostra um registo detalhado. Terceiro, se o erro estiver a ser gerado por um campo específico, verifique se está a usar um tipo obsoleto (search removido no Redux 3.x, divide renomeado). A lista atual de campos está sempre na documentação do Redux.

Vale a pena usar o Redux Framework em 2026

O Redux Framework é um produto maduro e ativamente mantido, com 32 milhões de downloads e uma comunidade de mais de 270 contribuidores no GitHub. Se está a construir um tema WordPress clássico ou híbrido e precisa de um painel de definições com um conjunto rico de campos, pré-visualização ao vivo no personalizador e CSS dinâmico, o Redux poupar-lhe-á semanas de desenvolvimento e dar-lhe-á um resultado que cumpre as normas de segurança do WordPress (PHPCS, escaping, validação).

Arquitetonicamente, a melhor forma de integrar é isolar a framework num plugin de tema dependente através de require_once com verificação class_exists. Isto proporciona uma base de código limpa, proteção contra conflitos de inclusão dupla e um caminho de atualização transparente.

Quando o Redux não é necessário: está a fazer um tema leve sem painel de definições; a trabalhar num ambiente FSE puro (tema de blocos com theme.json); já tem o ACF implementado com Options Pages para metacampos. Nestes casos, incluir o Redux apenas para um botão de ligar/desligar é como usar um canhão para matar pardais: a framework adicionará ~2 MB ao tamanho do tema sem benefício proporcional.

Antes de começar a trabalhar, consulte a documentação oficial no site dos developers do Redux e o repositório no GitHub; aí também pode reportar um bug ou propor uma funcionalidade. Se precisar de ajuda com um tipo de campo ou argumento específico, escreva nos comentários, resolvemos isso juntos.