O jeito que esse post ensinava antes — editar direto os arquivos dentro de wp-content/plugins/elementor/includes/ — é exatamente o que não fazer. Qualquer atualização do Elementor sobrescreve esses arquivos e apaga seu widget sem aviso nenhum. Já vi isso acontecer com cliente que perdeu um widget de checkout customizado numa atualização automática de madrugada. O jeito certo é criar um plugin próprio, separado do Elementor, que se conecta a ele pelos hooks oficiais.
Vou mostrar como montar isso do zero, incluindo o hook atual que substituiu o antigo widgets_registered nas versões recentes do Elementor.
Estrutura mínima do plugin
Crie uma pasta nova dentro de wp-content/plugins/, por exemplo meu-widget-elementor, com um arquivo principal:
<?php
/**
* Plugin Name: Meu Widget Elementor
* Description: Widget customizado para o Elementor
* Version: 1.0.0
*/
if (!defined('ABSPATH')) exit;
function meu_widget_registrar($widgets_manager) {
require_once(__DIR__ . '/widgets/class-meu-widget.php');
$widgets_manager->register(new \Meu_Widget_Elementor());
}
add_action('elementor/widgets/register', 'meu_widget_registrar');Repare que uso elementor/widgets/register, que é o hook atual. Se você encontrar tutorial por aí usando elementor/widgets/widgets_registered, saiba que esse hook é da geração anterior do Elementor e pode não disparar mais nas versões recentes — foi uma das causas mais comuns de “meu widget sumiu depois que atualizei o Elementor” que vi em fórum.
Criando a classe do widget
Dentro da pasta widgets/, crie class-meu-widget.php:
<?php
class Meu_Widget_Elementor extends \Elementor\Widget_Base {
public function get_name() { return 'meu_widget'; }
public function get_title() { return __('Meu Widget', 'meu-widget'); }
public function get_icon() { return 'eicon-code'; }
public function get_categories() { return ['basic']; }
protected function register_controls() {
$this->start_controls_section('conteudo_section', [
'label' => __('Conteúdo', 'meu-widget'),
]);
$this->add_control('titulo', [
'label' => __('Título', 'meu-widget'),
'type' => \Elementor\Controls_Manager::TEXT,
'default' => __('Título padrão', 'meu-widget'),
]);
$this->end_controls_section();
}
protected function render() {
$settings = $this->get_settings_for_display();
echo '<h3>' . esc_html($settings['titulo']) . '</h3>';
}
}Esse esqueleto já registra um widget funcional com um campo de texto editável no painel do Elementor. A partir daqui, você adiciona mais controles conforme a necessidade — texto, imagem, cor, repetidor de itens.
Criando uma categoria própria (opcional, mas recomendado)
Se você vai criar mais de um widget customizado, vale separar numa categoria própria em vez de jogar tudo em “Basic”:
function meu_widget_categoria($elements_manager) {
$elements_manager->add_category('minha-categoria', [
'title' => __('Meus Widgets', 'meu-widget'),
'icon' => 'fa fa-plug',
]);
}
add_action('elementor/elements/categories_registered', 'meu_widget_categoria');Depois é só trocar get_categories() na classe do widget para retornar ['minha-categoria'].
Erros comuns nessa configuração
“Class Elementor\Widget_Base not found”
Acontece quando o widget tenta carregar antes do Elementor estar disponível, geralmente porque foi registrado direto no init em vez do hook certo. Sempre registre dentro de elementor/widgets/register como no exemplo acima — esse hook só dispara depois que o Elementor já carregou suas próprias classes.
Widget aparece no painel mas não renderiza nada no site
Confira se o método render() está de fato dentro da classe certa e sem erro de sintaxe silencioso — ative WP_DEBUG temporariamente no wp-config.php para ver o erro real em vez de uma seção em branco.
Widget some depois de atualizar o Elementor
Se isso acontecer mesmo seguindo esse guia, confira se você não colocou os arquivos dentro da própria pasta do plugin do Elementor por engano. O plugin do seu widget precisa estar numa pasta separada e independente, ativado por conta própria em Plugins.
Testando sem quebrar o site em produção
Sempre desenvolva e teste um widget novo num ambiente de staging antes de ativar em produção. Um erro de sintaxe PHP num arquivo de widget carregado incorretamente pode gerar tela branca no site inteiro, não só no widget — então nunca edite isso direto no servidor de produção.
Perguntas frequentes
Preciso saber Elementor Pro para criar widget customizado?
Não, a API de widgets está disponível na versão gratuita do Elementor. Elementor Pro adiciona controles e recursos extras, mas o sistema de registro de widget é o mesmo.
Dá pra editar um widget nativo do Elementor em vez de criar um novo?
Tecnicamente sim, estendendo a classe do widget original, mas normalmente é melhor criar um widget novo do zero — editar comportamento de widget nativo tende a quebrar em atualizações futuras do Elementor de um jeito difícil de rastrear.
Meu widget customizado deixa o site mais lento?
Só se você carregar CSS/JS desnecessário em toda página. Use get_style_depends() e get_script_depends() para carregar os arquivos do widget somente nas páginas onde ele é usado, em vez de enfileirar globalmente.
Funciona igual no Elementor e no Elementor Pro?
Sim, a estrutura de registro é idêntica. A diferença é que o Pro libera categorias e tipos de controle adicionais para usar dentro do seu widget.
Vale usar um widget pronto de terceiros em vez de criar o meu?
Se o que você precisa já existe num addon confiável (Essential Addons, Happy Elementor Addons, JetElements), geralmente compensa mais usar o addon do que manter código próprio — menos manutenção pra você no longo prazo. Vale criar widget customizado mesmo quando a necessidade é bem específica do projeto e nenhum addon cobre direito.
Se esse widget vai fazer parte de um projeto maior que também precisa de um tipo de conteúdo customizado (não só um widget visual), o guia de como criar um Post Type customizado no WordPress é o complemento natural desse processo.
Carregando CSS e JS só onde o widget é usado
Em vez de enfileirar um arquivo de estilo globalmente com wp_enqueue_scripts, use os métodos próprios do widget para o Elementor carregar o arquivo só na página onde o widget realmente está:
public function get_style_depends() {
wp_register_style('meu-widget-style', plugins_url('css/estilo.css', __FILE__));
return ['meu-widget-style'];
}Isso evita o problema clássico de site WordPress cheio de widget que carrega CSS e JS de recurso que a página nem usa — um dos maiores vilões silenciosos de tempo de carregamento em site com Elementor.
