Complementary Area Toggle Demo

A WordPress plugin demonstrating advanced sidebar and UI control techniques in the WordPress block editor using the @wordpress/interface, @wordpress/commands, and @wordpress/editor packages.

📖 These examples are referenced in the blog post: Detecting and controlling sidebars in the Block Editor

What This Demo Shows

This plugin provides multiple practical examples of:

• ✅ Sidebar Control: Open/close document and block sidebars programmatically
• ✅ Custom Commands: Add custom commands to the WordPress command palette (Cmd+K / Ctrl+K)
• ✅ Dynamic Commands: Commands that change behavior based on UI state
• ✅ Smart Sidebar Logic: Context-aware sidebar toggling based on block selection
• ✅ Panel Control: Open specific panels within sidebars
• ✅ Inserter Control: Toggle and open specific tabs in the block inserter
• ✅ Custom Plugin Sidebar: Create and control custom sidebars with commands

Included Examples

1. OpenCloseDocumentSidebar - Basic sidebar commands using useCommand
2. OpenCloseDocumentSidebarAlt - Alternative approach using useCommandLoader
3. OpenCloseDocumentSidebarAlt2 - Another variant of sidebar control
4. SmartSidebar - Context-aware sidebar that opens block/document sidebar based on selection
5. CustomPluginSidebar - Custom sidebar with command palette integration
6. OpenSpecificPanel - Open specific panels (e.g., Categories) within sidebars
7. ToggleInserter - Control the block inserter programmatically
8. OpenInserterTabs - Open specific tabs (Patterns, Media) in the block inserter

Installation

1. Copy this folder to your WordPress wp-content/plugins/ directory
2. Run npm install to install dependencies
3. Run npm run build to build the JavaScript
4. Activate the plugin in WordPress admin

Usage

After activation:

1. Go to the post editor (or page editor)
2. Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) to open the command palette
3. You'll see several new custom commands available:
   • Open/Close Document Sidebar - Opens or closes the settings sidebar
   • Open/Close (smart) Sidebar - Smart toggle based on block selection context
   • Open/Close Custom Sidebar - Your custom plugin sidebar
   • Open/Close (specific) Categories Panel - Directly open the Categories panel
   • Open/Close Block Inserter - Toggle the block inserter
   • Open (specific) Patterns/Media Tab - Open specific inserter tabs
4. Type to search and select any command to see it in action
5. The custom sidebar is also accessible from the three-dot menu (⋮) in the sidebar

How It Works

Core Concepts

This plugin demonstrates several key WordPress editor APIs:

1. Interface Store (@wordpress/interface)

Controls complementary areas (sidebars) in the editor:

import { store as interfaceStore } from '@wordpress/interface';
import { useSelect, useDispatch } from '@wordpress/data';

const { enableComplementaryArea, disableComplementaryArea } = useDispatch(interfaceStore);

// Check which sidebar is active
const activeSidebar = useSelect((select) =>
  select(interfaceStore).getActiveComplementaryArea('core')
);

// Open a specific sidebar
enableComplementaryArea('core', 'edit-post/document');

// Close any sidebar
disableComplementaryArea('core');

2. Command Palette (@wordpress/commands)

Add custom commands accessible via Cmd+K:

Using useCommand (simpler approach):

import { useCommand } from '@wordpress/commands';

useCommand({
  name: 'my-plugin/toggle-sidebar',
  label: 'Toggle My Sidebar',
  icon: cog,
  callback: () => {
    // Your logic here
  },
  disabled: false, // Optional: disable based on state
});

Using useCommandLoader (dynamic commands):

import { useCommandLoader } from '@wordpress/commands';

const getSidebarCommands = () => function useSidebarCommands() {
  const commands = useMemo(() => {
    // Return array of commands based on current state
    return [{ name: 'cmd-1', label: 'Command 1', callback: () => {} }];
  }, [dependencies]);

  return { commands, isLoading: false };
};

useCommandLoader({
  name: 'my-plugin/commands',
  hook: getSidebarCommands(),
});

3. Edit Post Store (@wordpress/edit-post)

Controls panels and UI elements within the post editor:

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

const { openGeneralSidebar, toggleEditorPanelOpened } = useDispatch('core/edit-post');

// Check if a specific panel is open
const isPanelOpen = useSelect((select) =>
  select('core/edit-post').isEditorPanelOpened('taxonomy-panel-category')
);

// Open a specific panel
openGeneralSidebar('edit-post/document');
toggleEditorPanelOpened('taxonomy-panel-category');

4. Editor Store (@wordpress/editor)

Controls the block inserter:

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

const { setIsInserterOpened } = useDispatch('core/editor');

// Open inserter with specific tab
setIsInserterOpened({ tab: 'patterns' });
setIsInserterOpened({ tab: 'media' });

// Toggle inserter
setIsInserterOpened(!isInserterOpen);

Example Implementations

Smart Sidebar

The SmartSidebar.js component demonstrates context-aware behavior:

• Detects if a block is selected
• Opens the Block sidebar if a block is selected
• Opens the Document sidebar if no block is selected
• Single command that intelligently chooses the right sidebar

Dynamic Commands

OpenCloseDocumentSidebarAlt.js shows how to create commands that change based on state:

• Shows "Open Document Sidebar" when closed
• Shows "Close Document Sidebar" when open
• Commands update dynamically using useCommandLoader

Development

# Watch for changes during development
npm run start

# Build for production
npm run build

File Structure

complementary-area-toggle-demo/
├── complementary-area-toggle-demo.php    # Main plugin file
├── package.json                           # Build configuration
├── src/
│   ├── index.js                          # Plugin registration
│   └── components/
│       ├── OpenCloseDocumentSidebar.js   # Basic sidebar commands
│       ├── OpenCloseDocumentSidebarAlt.js # useCommandLoader example
│       ├── OpenCloseDocumentSidebarAlt2.js # Alternative variant
│       ├── SmartSidebar.js               # Context-aware sidebar
│       ├── CustomPluginSidebar.js        # Custom sidebar with commands
│       ├── OpenSpecificPanel.js          # Panel control example
│       ├── ToggleInserter.js             # Inserter control
│       └── OpenInserterTabs.js           # Inserter tab control
└── build/                                 # Compiled JavaScript (generated)

Key Packages Used

• @wordpress/interface - Sidebar/complementary area control
• @wordpress/commands - Command palette integration
• @wordpress/edit-post - Post editor UI control
• @wordpress/editor - Block inserter control
• @wordpress/data - State management (useSelect, useDispatch)
• @wordpress/plugins - Plugin registration
• @wordpress/components - UI components