@wordpress/edit-widgets

Overview

The @wordpress/edit-widgets package provides the block-based Widgets editor screen for WordPress. It bridges the gap between traditional widgets and modern blocks, allowing you to use both in widget areas while maintaining full backward compatibility.

This package is designed for WordPress core and may not be fully documented for external use. However, you can use it in your own projects with the understanding that APIs may evolve.

Three-Layer Architecture

The Widgets editor follows the same three-layer architecture as other WordPress editors:

block-editor (WordPress-agnostic, generic editing)
    ↓
editor (WordPress entity-aware functionality) 
    ↓
edit-widgets (Widgets editor screen with widget areas)

Layer Responsibilities

@wordpress/block-editor - Generic block editing canvas. Provides the foundation for block manipulation.
@wordpress/editor - WordPress entity management. Handles entity persistence and data operations.
@wordpress/edit-widgets - Widgets screen implementation. Manages widget areas (sidebars), widget-to-block translation, and legacy widget compatibility.

The widgets editor must bridge two worlds: traditional widgets and modern blocks. This package contains translation mechanisms to ensure both work seamlessly together.

Installation

Install the package via npm:

npm install @wordpress/edit-widgets

Environment Requirements: This package requires an ES2015+ environment. If you’re targeting older environments, include the polyfill from @wordpress/babel-preset-default.

How the Widgets Editor Works

The new Widgets editor in WordPress admin is another block editor, just like the post editor or site editor. However, it has a unique challenge: it must support both Gutenberg blocks and traditional widgets.

The Translation Mechanism

To support both widgets and blocks, the editor employs a bidirectional translation mechanism: A widget block acts as a block UI wrapper for widget data. This allows traditional widgets to be edited within the block editor:

Edit Mode - Shows the standard widget form (the same form you’d see in the old widgets screen)
Preview Mode - Displays a server-side render of the widget output

Traditional Widget → Widget Block → Editable in Block Editor

A block widget acts as a storage mechanism for blocks added to widget areas. This is a special HTML widget that stores block markup:

All blocks added to widget areas are stored as these special HTML widgets
The block data is stored as it’s rendered by the block’s save function
This ensures complete compatibility with the old widgets screen

Gutenberg Block → Block Widget (HTML Widget) → Stored in Database

This dual translation mechanism ensures 100% compatibility with the old widgets screen. If the block-based editor breaks some widget functionality, you can easily revert to the old screen and continue editing legacy widgets.

The widgets editor manages widget areas, also known as sidebars:

import { useSelect, useDispatch } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';

// Get all widget areas
const widgetAreas = useSelect((select) => {
  return select(coreStore).getEntityRecords('root', 'sidebar', {
    per_page: -1,
  });
}, []);

// Get widgets in a specific area
const widgets = useSelect((select) => {
  return select(coreStore).getEntityRecords('root', 'widget', {
    sidebar: 'sidebar-1',
  });
}, []);

Adding Widgets to Areas

import { useDispatch } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';

const { saveEntityRecord } = useDispatch(coreStore);

// Add a new widget to an area
await saveEntityRecord('root', 'widget', {
  sidebar: 'sidebar-1',
  id_base: 'text',
  instance: {
    encoded: btoa(JSON.stringify({
      title: 'My Text Widget',
      text: 'Widget content here',
    })),
  },
});

REST API Endpoints

The widgets editor uses several dedicated REST API endpoints:

Widgets Endpoint (`/wp/v2/widgets`)

Used to:

Load and save widgets
Retrieve server-side render of widget edit forms
Manage widget instances

Sidebars Endpoint (`/wp/v2/sidebars`)

Used to:

List available widget areas
Assign widgets to widget areas
Remove widgets from widget areas

Used to:

List available widget types (e.g., text widget, calendar widget)
Get widget type information and capabilities
Determine which widgets support block transformations

To make the experience seamless for users, the widgets editor automatically registers widget block variations:

// For every available widget, a variation is registered
// For example, a "Text Widget" variation, "Calendar Widget" variation, etc.

This means users can:

Search for widgets by their exact name
Insert widgets using the block inserter
See familiar widget names instead of generic “Widget” block

Hiding Redundant Widgets

Widgets that have block equivalents can be hidden to avoid confusion:

// Core widgets with block equivalents are automatically hidden
// For example:
// - Archives Widget → Archives Block
// - Categories Widget → Categories Block  
// - Calendar Widget → Calendar Block
// - RSS Widget → RSS Block

You can control this behavior using filters:

// In your theme or plugin
add_filter('widget_types_to_hide_from_legacy_widget_block', function($widgets) {
  $widgets[] = 'my_custom_widget'; // Hide your custom widget
  return $widgets;
});

All core widgets that have block equivalents are automatically hidden in the widgets editor. Users should use the block versions for better compatibility and features.

The widgets editor provides full backward compatibility: Traditional widget forms are embedded within the block editor:

User inserts a widget block and selects a widget type
The editor loads the widget’s edit form via AJAX
The form is rendered within the block editor interface
Changes are auto-saved as the user edits
Widget data is stored in the traditional widget format

Fallback to Classic Widgets Screen

If you encounter compatibility issues:

// Disable the block-based widgets editor
add_filter('use_widgets_block_editor', '__return_false');

This reverts to the classic widgets screen while preserving all widget data.

If the new widgets editor breaks widget functionality that depends on specific HTML structure or jQuery events, you can safely revert to the old screen without losing data.

Block Editor Settings

You can customize the widgets editor behavior:

const widgetEditorSettings = {
  // Disable certain blocks in widget areas
  allowedBlockTypes: [
    'core/paragraph',
    'core/heading',
    'core/image',
    'core/list',
    // ... other allowed blocks
  ],
  
  // Disable block templates
  template: null,
  
  // Widget-specific settings
  widgetAreas: [
    {
      id: 'sidebar-1',
      name: 'Primary Sidebar',
      description: 'Main sidebar area',
    },
  ],
};

Widget data follows a specific structure:

import { useSelect, useDispatch } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';

// Read widget data
const widget = useSelect((select) => {
  return select(coreStore).getEntityRecord('root', 'widget', widgetId);
}, [widgetId]);

// Widget object structure:
// {
//   id: 'text-1',
//   id_base: 'text',
//   sidebar: 'sidebar-1',
//   rendered: '<div>...</div>',
//   rendered_form: '<form>...</form>',
//   instance: {
//     encoded: 'base64-encoded-data',
//     hash: 'hash-value',
//     raw: { title: '...', text: '...' }
//   }
// }

// Update widget
const { editEntityRecord, saveEditedEntityRecord } = useDispatch(coreStore);

editEntityRecord('root', 'widget', widgetId, {
  instance: {
    raw: {
      title: 'Updated Widget Title',
      text: 'Updated widget content',
    },
  },
});

await saveEditedEntityRecord('root', 'widget', widgetId);

Batch Processing

This package contains an experimental batch processing feature:

The core/__experimental-batch-processing store is highly experimental and considered a private API. It may evolve or be removed in future versions.

import { useDispatch } from '@wordpress/data';

// Access experimental batch processing (private API)
const { processBatch } = useDispatch('core/__experimental-batch-processing');

// Use for batch operations on multiple widgets

This feature may eventually become a separate @wordpress/batch-processing package. You can programmatically manage widget areas:

// Register a new widget area in your theme
register_sidebar(array(
  'name'          => 'Footer Widget Area',
  'id'            => 'footer-1',
  'description'   => 'Appears in the footer',
  'before_widget' => '<div id="%1$s" class="widget %2$s">',
  'after_widget'  => '</div>',
  'before_title'  => '<h3 class="widget-title">',
  'after_title'   => '</h3>',
));

The widget area automatically appears in the widgets editor.

Common Use Cases

Migrating from Classic Widgets to Blocks

To encourage users to migrate from widgets to blocks:

Identify widgets with block equivalents
Hide the legacy widgets using filters
Provide documentation on equivalent blocks
Consider creating custom blocks for specialized widgets

Supporting Custom Legacy Widgets

If you have custom widgets that don’t have block equivalents:

// Ensure your widget is compatible
class My_Custom_Widget extends WP_Widget {
  public function form($instance) {
    // Return proper form HTML
    // The widgets editor will embed this form
  }
  
  public function update($new_instance, $old_instance) {
    // Sanitize and return updated instance
  }
  
  public function widget($args, $instance) {
    // Render widget output
  }
}

The widgets editor automatically supports your custom widget through the widget block wrapper.

@wordpress/block-editor - Generic block editing functionality
@wordpress/editor - WordPress entity-aware editor features
@wordpress/core-data - WordPress entity management and REST API integration
@wordpress/widgets - Widget management utilities
@wordpress/interface - Shared interface components

Core Packages

UI Components

Editor Implementations

Developer Tools

Utilities

Overview

Three-Layer Architecture

Layer Responsibilities

Installation

How the Widgets Editor Works

The Translation Mechanism

Widget Block (Widgets as Blocks)

Block Widget (Blocks as Widgets)

Widget Areas (Sidebars)

Adding Widgets to Areas

REST API Endpoints

Widgets Endpoint (`/wp/v2/widgets`)

Sidebars Endpoint (`/wp/v2/sidebars`)

Widget Types Endpoint (`/wp/v2/widget-types`)

Widget Block Variations

Hiding Redundant Widgets

Legacy Widget Compatibility

Widget Form Integration

Fallback to Classic Widgets Screen

Block Editor Settings

Working with Widget Data

Batch Processing

Customizing Widget Areas

Common Use Cases

Migrating from Classic Widgets to Blocks

Supporting Custom Legacy Widgets

Resources

​Overview

​Three-Layer Architecture

​Layer Responsibilities

​Installation

​How the Widgets Editor Works

​The Translation Mechanism

​Widget Block (Widgets as Blocks)

​Block Widget (Blocks as Widgets)

​Widget Areas (Sidebars)

​Adding Widgets to Areas

​REST API Endpoints

​Widgets Endpoint (/wp/v2/widgets)

​Sidebars Endpoint (/wp/v2/sidebars)

​Widget Types Endpoint (/wp/v2/widget-types)

​Widget Block Variations

​Hiding Redundant Widgets

​Legacy Widget Compatibility

​Widget Form Integration

​Fallback to Classic Widgets Screen

​Block Editor Settings

​Working with Widget Data

​Batch Processing

​Customizing Widget Areas

​Common Use Cases

​Migrating from Classic Widgets to Blocks

​Supporting Custom Legacy Widgets

​Related Packages

​Resources

Overview

Three-Layer Architecture

Layer Responsibilities

Installation

How the Widgets Editor Works

The Translation Mechanism

Widget Block (Widgets as Blocks)

Block Widget (Blocks as Widgets)

Widget Areas (Sidebars)

Adding Widgets to Areas

REST API Endpoints

Widgets Endpoint (`/wp/v2/widgets`)

Sidebars Endpoint (`/wp/v2/sidebars`)

Widget Types Endpoint (`/wp/v2/widget-types`)

Widget Block Variations

Hiding Redundant Widgets

Legacy Widget Compatibility

Widget Form Integration

Fallback to Classic Widgets Screen

Block Editor Settings

Working with Widget Data

Batch Processing

Customizing Widget Areas

Common Use Cases

Migrating from Classic Widgets to Blocks

Supporting Custom Legacy Widgets

Related Packages

Resources