O que é um widget no WordPress
Widget é um bloco de conteúdo independente que o WordPress exibe em áreas fixas do tema, como barra lateral, rodapé ou topo. Busca, posts recentes, categorias e texto livre são os usos mais comuns. Quem define onde ficam as áreas é o tema, e o que entra em cada uma se escolhe no painel. Para o contexto geral da plataforma, que a W3Techs media em 40,2% de todos os sites em 25/09/2026, o guia sobre o que é WordPress é o ponto de partida.
A atualização do núcleo para o WordPress 5.8 mudou a tela de widgets dos temas clássicos: ela passou a usar o editor de blocos, resultado do projeto Gutenberg, e widgets de plugins que ainda não viraram bloco aparecem pelo bloco Widget antigo, segundo a documentação do editor de widgets em blocos[1]. A mesma página informa que temas de blocos, como o Twenty Twenty-Five, removem a tela de widgets de propósito, e o conteúdo de barra lateral ou rodapé fica em blocos, padrões ou partes de template no Editor do site. Numa instalação nova do WordPress, o tema padrão já é de blocos, então a tela de widgets só aparece depois de ativar um tema clássico.
O Elementor usa o mesmo nome para outra coisa: lá, widgets são componentes do construtor de páginas, criados com a classe Widget_Base e o gancho elementor/widgets/register, conforme a documentação de desenvolvedores do Elementor[2]. Este guia trata dos widgets do WordPress, mas fica uma dica para quem usa o construtor: se o layout dos widgets do Elementor quebrar depois de uma limpeza de cache, regenere os arquivos CSS em Elementor > Ferramentas antes de investigar o código.
O que é preciso antes de começar
Os pré-requisitos mudam conforme o caminho escolhido, e a lista abaixo cobre os três:
- Tipo de tema identificado: tema clássico tem tela de widgets; tema de blocos usa o Editor do site.
- Acesso de administrador ao painel: para usar a tela de widgets e o Personalizador.
- Acesso aos arquivos do tema filho ou de um plugin: para registrar área ou programar widget, por SFTP, painel da hospedagem ou repositório.
- Ambiente de homologação: cópia do site com o mesmo tema, plugins e versão de PHP, onde o código é testado antes de ir ao ar.
- WP-CLI (opcional): ferramenta de linha de comando do WordPress, útil para conferir widgets e áreas sem abrir o painel.
Passo a passo para criar widget no WordPress
- Conferir as áreas existentes (painel, menu Aparência, opção Widgets). Cada área registrada pelo tema aparece como um grupo. Se a área desejada já existe, o botão de adicionar abre a biblioteca de blocos e o trabalho acaba nesse ponto.
- Registrar uma área nova (arquivo
functions.phpdo tema filho). A função register_sidebar() é chamada no gancho widgets_init, conforme a referência de register_sidebar()[3]. O id precisa ser único, em minúsculas e sem espaços; desde o WordPress 4.2, omitir o id gera aviso. - Exibir a área no template (arquivo do tema, como footer.php). A função is_active_sidebar() confere se há widgets na área, e dynamic_sidebar() imprime o conteúdo, como no exemplo da referência de dynamic_sidebar()[4]. No tema filho, copie o footer.php do tema pai e insira a chamada; o arquivo copiado deixa de receber as atualizações do tema pai, então revise-o quando o tema pai mudar.
- Programar o widget próprio (arquivo PHP de um plugin). A classe estende WP_Widget e implementa quatro métodos, descritos no manual de temas do WordPress[5]: __construct() define id, nome e descrição; widget() gera o HTML do site; form() monta o formulário do painel com get_field_id() e get_field_name(); update() limpa e salva os dados, e com sanitize_text_field() um código malicioso digitado no campo é removido antes de ir para o banco.
- Registrar o widget (mesmo arquivo do plugin). A função register_widget(), no gancho widgets_init, deixa o widget disponível na tela de widgets.
- Adicionar e configurar (painel ou WP-CLI). O widget aparece na tela de widgets, dentro do bloco Widget antigo, e pode ser colocado na área nova e configurado pelo formulário que o método form() monta.
Código do passo 2:
“`php
add_action( ‘widgets_init’, ‘sv_registrar_areas’ );
function sv_registrar_areas() {
register_sidebar( array(
‘name’ => __( ‘Rodapé’, ‘textdomain’ ),
‘id’ => ‘rodape-1’,
‘before_widget’ => ‘
‘,‘before_title’ => ‘
‘,
‘after_title’ => ‘‘,
) );
}
`
Nos exemplos, troque textdomain pelo identificador de tradução do seu tema ou plugin, porque com o valor genérico a tradução dos textos não funciona.
Código do passo 3:
“`php
`
Código dos passos 4 e 5, com os quatro métodos:
“`php
class SV_Widget_Contato extends WP_Widget {
public function __construct() {
parent::__construct(
‘sv_contato’,
__( ‘Contato’, ‘textdomain’ ),
array( ‘description’ => __( ‘Telefone de contato’, ‘textdomain’ ) )
);
}
public function widget( $args, $instance ) {
if ( empty( $instance[‘telefone’] ) ) {
return;
}
echo $args[‘before_widget’];
echo ‘
‘ . esc_html( $instance[‘telefone’] ) . ‘
‘;echo $args[‘after_widget’];
}
public function form( $instance ) {
$telefone = $instance[‘telefone’] ?? ”;
?>
return ”;
}
public function update( $new_instance, $old_instance ) {
return array( ‘telefone’ => sanitize_text_field( $new_instance[‘telefone’] ?? ” ) );
}
}
add_action( ‘widgets_init’, function () {
register_widget( ‘SV_Widget_Contato’ );
} );
`
O método form() é obrigatório na prática: sem ele, o painel mostra a mensagem “Não há opções para este widget”, o telefone nunca é salvo e o widget não imprime nada no site. Os três trechos foram testados em WordPress 7.1.3 com PHP 8.3, num tema filho do Twenty Twenty-One, em 14/10/2026: a área Rodapé apareceu registrada, o site imprimiu o telefone e, com a área vazia, não imprimiu nada, sem aviso no log de depuração.
O prefixo sv_ reduz o risco de colisão com outros plugins. Já o código do widget fica num plugin para continuar funcionando depois de uma troca de tema, e a estrutura mínima desse plugin está no guia sobre como criar plugin WordPress.
Quanto tempo leva
O prazo depende do caminho. Colocar blocos numa área existente dispensa código, enquanto registrar e exibir uma área nova envolve editar o tema filho e publicar. Um widget programado soma desenvolvimento, revisão de segurança e teste em homologação.
Nos projetos da Studio Visual, o esforço varia com o tipo de trabalho. A tarefa mais curta é o ajuste pontual numa área existente, como corrigir um widget do rodapé. Widgets simples de um site novo, como uma nuvem de tags montada com a função nativa wp_tag_cloud(), pedem um pouco mais. Widgets com consulta própria ou integração, como lista de mais lidos ou chat de atendimento, levam várias vezes esse tempo, e um componente com regra de negócio complexa, como uma calculadora, vira um projeto à parte.
Quando o widget faz parte de um projeto maior, o prazo entra no cronograma do site todo, assunto do guia quanto tempo leva para criar um site.
Widget, bloco ou padrão: como escolher
| Situação | Caminho indicado | Motivo |
|---|---|---|
| Texto, imagem ou links fixos em tema clássico | Bloco na tela de widgets | Sem código e editável por quem cuida do conteúdo |
| Área nova no layout de tema clássico | register_sidebar() e dynamic_sidebar() | A área passa a existir no painel e no template |
| Conteúdo com regra própria (consulta a posts, dado externo, campo personalizado) | Widget com WP_Widget ou bloco programado | Bloco pronto não cobre a lógica |
| Widget de plugin antigo em tema clássico | Bloco Widget antigo | Mantém a configuração existente |
| Tema de blocos | Bloco, padrão ou parte de template no Editor do site | A tela de widgets não existe nesse tipo de tema |
Para quem prefere um bloco próprio, o fluxo é outro, documentado no manual do editor de blocos[6], e costuma ser o ponto de partida em site novo com tema de blocos.
Erros mais comuns ao criar widget
- Editar o tema principal: a próxima atualização do tema apaga o código; o registro de área vai no tema filho e o widget, num plugin.
- Registrar área sem id ou com id em maiúsculas: gera aviso e pode trocar a área de lugar quando outra for registrada.
- Imprimir dado sem escapar: o manual de segurança[7] pede esc_html(), esc_attr() ou esc_url() conforme o contexto, o mais perto possível da saída.
- Salvar sem sanitizar: tudo que vem do formulário passa por funções como sanitize_text_field() no método update().
- Esquecer is_active_sidebar(): a área vazia deixa HTML sobrando no layout.
- Testar só no site em produção: um erro de PHP no widget aparece em todas as páginas que exibem a área.
Como validar que deu certo
- Na tela de widgets, a área nova aparece com o nome registrado e aceita o widget.
- No site, o widget aparece na posição esperada, em desktop e celular, e some quando a área fica vazia.
- Pela linha de comando, o comando wp widget[8] do WP-CLI lista o que está na área e os valores salvos, por exemplo wp widget list rodape-1 –fields=name,id,position,options, o que permite validar sem abrir o painel.
- Em homologação, o log de depuração fica sem avisos ligados ao widget. A página de depuração do WordPress[9] indica ativar WP_DEBUG e WP_DEBUG_LOG, que grava os erros em wp-content/debug.log, e desaconselha usar a depuração em site no ar.
- Depois de cada core update e de cada atualização do tema, o teste se repete.
O que fazer quando dá errado
Quando a área não aparece no painel, a causa costuma estar no gancho: register_sidebar() precisa rodar em widgets_init, e o arquivo precisa estar no tema ativo. Se aparece no painel e não no site, falta a chamada a dynamic_sidebar() no template certo. Se o widget quebra a página, desative o plugin que o contém, pelo painel ou com wp plugin deactivate no WP-CLI, leia o debug.log em homologação e corrija antes de reativar. Para retirar um widget sem apagar o código, a função unregister_widget(), no gancho widgets_init, remove o widget da lista, conforme a referência de unregister_widget()[10].
O que a experiência da Studio Visual mostra
Na Studio Visual, criar e ajustar widgets é demanda frequente nos sites WordPress que mantemos, principalmente em rodapés, barras laterais e áreas que o cliente precisa editar sem mexer no código.
No novo site da Revista Oeste, revista digital, em janeiro de 2023, a barra lateral foi montada com seis widgets próprios: nuvem de tags, conteúdos relacionados, colunistas, mais lidas, um canal próprio da revista e um bloco institucional. O esforço acompanhou a lógica de cada um: a nuvem de tags, que aproveitou a função nativa wp_tag_cloud() do WordPress, foi a mais rápida; a lista de mais lidas, que depende de consulta própria, levou várias vezes mais.
OPINIÃO DE ESPECIALISTA
“Widget programado faz sentido para manter um site com tema clássico, só que para começar um projeto novo a base hoje é outra. Nos sites recentes, nossa base de componentes foi para blocos, porque o tema de blocos nem mostra a tela de widgets e o conteúdo fica editável no mesmo lugar que o resto da página. Também já vi um módulo inteiro sumir do site depois de uma troca de versão do tema, porque a lógica morava no tema, fora de um plugin. Se o cliente precisa de algo numa área fixa, com regra de negócio, prefiro um bloco ou um plugin pequeno, versionado e testado em homologação.”
Vale fazer sozinho ou contratar
Colocar blocos na tela de widgets é tarefa de quem administra o conteúdo. Registrar área e programar widget exige PHP, acesso aos arquivos, ambiente de homologação e alguém para manter o código a cada atualização do WordPress. Quando a equipe não reúne essas condições, faz sentido contratar. Para dimensionar o investimento de um projeto de site que inclui esse tipo de trabalho, o guia quanto custa criar um site reúne os fatores de preço. Quem avalia outros caminhos para o site pode comparar com a opção de criar site com IA.
Para widgets e áreas que fazem parte de um tema sob medida, a página de especialista em WordPress mostra como a Studio Visual trabalha com desenvolvimento na plataforma.
