Building Custom Elementor Widgets with React & the WordPress REST API — a Practical Guide

Introduction

Elementor is one of the most powerful page builders in the WordPress ecosystem. While its built-in widgets cover most design needs, creating custom widgets allows developers to craft truly unique, data-driven, and interactive user experiences.

In this post, we’ll walk through how to build a custom Elementor widget that uses React for the frontend, PHP for registration and logic, and the WordPress REST API for dynamic data fetching.

You’ll learn how to:

• Scaffold a lightweight WordPress plugin structure.

• Build the widget interface with React.

• Fetch real WordPress data using the REST API.

• Properly enqueue and localize assets.

• Package and deploy your widget like a pro.

What You’ll Need

Before you begin, make sure you have:

• WordPress (latest version)

• Elementor (free or Pro)

• Node.js & npm installed

• Basic knowledge of PHP, JavaScript, and React

Step 1: Plugin Structure

Create a folder called elementor-react-widget and add the main plugin file elementor-react-widget.php:

<?php
/**
 * Plugin Name: Elementor React Widget
 * Description: A custom Elementor widget powered by React and the WP REST API.
 * Version: 1.0.0
 * Author: Nima Fadai
 */

if ( ! defined( 'ABSPATH' ) ) exit;

final class ERW_Plugin {
    const VERSION = '1.0.0';
    const SLUG = 'erw';

    public function __construct() {
        add_action( 'init', [ $this, 'register_assets' ] );
        add_action( 'elementor/widgets/register', [ $this, 'register_widget' ] );
    }

    public function register_assets() {
        $dir = plugin_dir_url( __FILE__ );
        wp_register_script(
            self::SLUG . '-app',
            $dir . 'build/index.js',
            [ 'wp-element', 'wp-api' ],
            self::VERSION,
            true
        );

        wp_localize_script( self::SLUG . '-app', 'ERW_Settings', [
            'rest_url' => esc_url_raw( rest_url() ),
            'nonce'    => wp_create_nonce( 'wp_rest' ),
        ]);

        wp_register_style( self::SLUG . '-styles', $dir . 'build/styles.css', [], self::VERSION );
    }

    public function register_widget( $widgets_manager ) {
        require_once __DIR__ . '/widgets/class-erw-widget.php';
        $widgets_manager->register( new \ERW_Widget() );
    }
}

new ERW_Plugin();

This PHP file registers scripts, styles, and your Elementor widget using WordPress hooks.

Step 2: The Widget Class

Inside a new folder widgets/, create the file class-erw-widget.php:

<?php
if ( ! defined( 'ABSPATH' ) ) exit;

use Elementor\Widget_Base;
use Elementor\Controls_Manager;

class ERW_Widget extends Widget_Base {
    public function get_name() {
        return 'erw_react_widget';
    }

    public function get_title() {
        return 'React Elementor Widget';
    }

    public function get_icon() {
        return 'eicon-code';
    }

    public function get_categories() {
        return [ 'general' ];
    }

    protected function register_controls() {
        $this->start_controls_section('content_section', [
            'label' => 'Content',
            'tab' => Controls_Manager::TAB_CONTENT,
        ]);

        $this->add_control('title', [
            'label' => 'Title',
            'type' => Controls_Manager::TEXT,
            'default' => 'Hello from React Widget',
        ]);

        $this->end_controls_section();
    }

    protected function render() {
        $settings = $this->get_settings_for_display();
        echo '<div class="erw-root" data-title="' . esc_attr( $settings['title'] ) . '"></div>';
        wp_enqueue_script( 'erw-app' );
        wp_enqueue_style( 'erw-styles' );
    }
}

This class defines the Elementor widget, adds a basic text control, and renders a

for React to mount into.

Step 3: The React App

Inside your plugin folder, create a src/ directory and a file src/index.js:

import React from 'react';
import { createRoot } from 'react-dom/client';

function App({ mountEl }) {
  const title = mountEl.dataset.title || 'Default Title';
  const [posts, setPosts] = React.useState([]);
  const [loading, setLoading] = React.useState(true);

  React.useEffect(() => {
    async function fetchPosts() {
      try {
        const response = await fetch(`${ERW_Settings.rest_url}wp/v2/posts?per_page=5`, {
          headers: { 'X-WP-Nonce': ERW_Settings.nonce }
        });
        const data = await response.json();
        setPosts(data);
      } catch (err) {
        console.error('Error fetching posts:', err);
      } finally {
        setLoading(false);
      }
    }
    fetchPosts();
  }, []);

  return (
    <div className="erw-widget">
      <h3>{title}</h3>
      {loading ? <p>Loading...</p> : (
        <ul>
          {posts.map(post => (
            <li key={post.id}>
              <a href={post.link}>{post.title.rendered}</a>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

document.addEventListener('DOMContentLoaded', () => {
  const roots = document.querySelectorAll('.erw-root');
  roots.forEach(el => {
    const root = createRoot(el);
    root.render(<App mountEl={el} />);
  });
});

This code dynamically fetches recent WordPress posts and displays them inside your Elementor widget.

Step 4: Build the React Bundle

You can use Vite, Webpack, or any preferred bundler.

Example setup with Vite:

npm create vite@latest elementor-react-widget --template react

Then adjust the build.outDir in vite.config.js to ../build, so your compiled JS lands in your plugin’s build folder.
Finally run:

npm run build

Step 5: Security & Optimization Tips

• Always use wp_create_nonce() for API security.

• Minify JS and CSS in production.

• Use lazy loading for large data.

• Avoid global namespace conflicts by prefixing your functions and scripts.

• Cache REST API responses where possible.

Step 6: Packaging & Testing

• Add a proper readme.txt file with plugin information.

• Test it inside Elementor’s editor to confirm compatibility.

• Document any dependencies or build steps.

Once confirmed, your plugin is production-ready — you’ve just built a React-powered Elementor widget connected to live WordPress data!

Conclusion

Combining React, WordPress, and Elementor creates limitless opportunities for web innovation.
By separating logic (PHP) from the UI (React), you gain scalability, flexibility, and a modern workflow that aligns with today’s front-end development standards.

Whether you’re building internal tools, client dashboards, or interactive UI blocks — this hybrid approach bridges the gap between WordPress tradition and modern web technology.

FAQs
1. Why use React for Elementor widgets?
React provides better state management, reactivity, and scalability for dynamic UIs.

2. Does this affect Elementor performance?
No — as long as you properly enqueue and scope scripts, your widget will run smoothly.

3. Can I integrate custom REST endpoints?
Yes. You can register custom routes with register_rest_route() in PHP and consume them in React.

4. Is this compatible with Elementor Pro?
Absolutely. It behaves like any native widget and can coexist with Pro features.

5. How do I optimize the build size?
Use production mode builds, tree-shaking, and CDN caching for static files.

6. Can I extend this widget for client dashboards?
Definitely — just modify the REST endpoint or connect to external APIs.