How to Add Custom Preview Devices to WordPress: Customizer and Block Editor

WordPress offers two distinct preview systems: the Customizer's device preview and the Block Editor's "Preview in new tab" dropdown. Both are extensible, but they require completely different approaches. I dug into both.

Two Separate APIs

The term "editor preview" is ambiguous in WordPress. The Customizer uses PHP hooks. The Block Editor uses React components. Do not confuse them.

Extension approach comparison

Feature	Customizer Preview	Block Editor Preview
Extension method	PHP filter + action	React component (Slot/Fill)
Build tools needed	None	@wordpress/scripts required
Location	Appearance > Customize	Post/page editor dropdown
What you add	Device sizes with dimensions	Menu items with links or actions
Key hook/component	customize_previewable_devices	PluginPreviewMenuItem

Part 1: Customizer device preview (PHP)

The WordPress Customizer shows device preview buttons for Desktop, Tablet, and Mobile. I can add custom device sizes using PHP hooks.

Architecture

1. Register your custom devices

Add this to your theme's functions.php. This hooks into customize_previewable_devices to add "Laptop" and "Large Mobile" options.

functions.php

<?php
/**
 * Add custom device sizes to the WordPress Customizer.
 *
 * @param array $devices Existing previewable devices.
 * @return array Modified array of previewable devices.
 */
function my_custom_preview_devices( $devices ) {
    $devices['laptop'] = array(
        'label'    => __( 'Laptop', 'your-text-domain' ),
        'width'    => 1280,
        'height'   => 800,
    );

    $devices['large_mobile'] = array(
        'label'    => __( 'Large Mobile', 'your-text-domain' ),
        'width'    => 414,
        'height'   => 896,
    );

    return $devices;
}
add_filter( 'customize_previewable_devices', 'my_custom_preview_devices' );
?>

2. Add CSS for preview dimensions

Register the CSS that resizes the preview pane for your custom devices.

functions.php

<?php
/**
 * Enqueue custom styles for the WordPress Customizer device previews.
 */
function my_custom_preview_styles() {
    ?>
    &lt;style type="text/css">
        .wp-customizer .preview-laptop .wp-full-overlay-main {
            width: 1280px;
            height: 800px;
            margin-left: -640px;
            margin-top: -400px;
            left: 50%;
            top: 50%;
        }

        .wp-customizer .preview-large_mobile .wp-full-overlay-main {
            width: 414px;
            height: 896px;
            margin-left: -207px;
            margin-top: -448px;
            left: 50%;
            top: 50%;
        }
    </style>
    <?php
}
add_action( 'customize_controls_print_styles', 'my_custom_preview_styles' );
?>

---

Part 2: Block Editor preview dropdown (React)

The Block Editor's "Preview in new tab" dropdown is a completely different system. You extend it with the PluginPreviewMenuItem React component from @wordpress/editor, using the editor's Slot/Fill pattern.

Architecture

1. Enqueue the editor script

Tell WordPress to load your script on the editor screen:

functions.php

<?php
function my_theme_enqueue_editor_scripts() {
    $asset_file_path = get_theme_file_path('build/editor.asset.php');

    if (file_exists($asset_file_path)) {
        $asset_file = include($asset_file_path);

        wp_enqueue_script(
            'my-theme-editor-extensions',
            get_theme_file_uri('build/editor.js'),
            $asset_file['dependencies'],
            $asset_file['version'],
            true
        );
    }
}
add_action('enqueue_block_editor_assets', 'my_theme_enqueue_editor_scripts');

note

This assumes you have a build process (like @wordpress/scripts) generating build/editor.js and build/editor.asset.php.

2. Register custom menu items

Create assets/js/editor.js with both a direct link and a JavaScript action:

assets/js/editor.js

import { __ } from '@wordpress/i18n';
import { registerPlugin } from '@wordpress/plugins';
import { PluginPreviewMenuItem } from '@wordpress/editor';
import { store as coreStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';

const MyCustomPreviewItems = () => {
    const { siteUrl, postPreviewLink } = useSelect((select) => {
        const { getSite } = select(coreStore);
        return {
            siteUrl: getSite()?.url,
            postPreviewLink: select('core/editor').getPermalink(),
        };
    }, []);

    const openSocialPreview = () => {
        if (postPreviewLink) {
            window.open(`${postPreviewLink}&preview_mode=social`, '_blank');
        }
    };

    return (
        <>
            {/* Direct link to Dark Mode Preview */}
            <PluginPreviewMenuItem
                href={`${postPreviewLink}&theme_mode=dark`}
                target="_blank"
            >
                {__('Preview in Dark Mode', 'my-theme')}
            </PluginPreviewMenuItem>

            {/* Custom onClick action */}
            <PluginPreviewMenuItem onClick={openSocialPreview}>
                {__('Social Card Preview', 'my-theme')}
            </PluginPreviewMenuItem>
        </>
    );
};

registerPlugin('my-theme-custom-preview-items', {
    render: MyCustomPreviewItems,
});

PluginPreviewMenuItem props reference

Prop	Type	Description
href	string	URL to open in a new tab
target	string	Link target (typically _blank)
onClick	function	Custom click handler
children	ReactNode	Menu item label text

You can mix href links and onClick handlers across multiple PluginPreviewMenuItem components.

Migration checklist

• Identify which preview system to extend (Customizer vs. Block Editor)
• For Customizer: add customize_previewable_devices filter
• For Customizer: add customize_controls_print_styles CSS
• For Block Editor: set up @wordpress/scripts build process
• For Block Editor: create PluginPreviewMenuItem component
• For Block Editor: enqueue via enqueue_block_editor_assets
• Test in WordPress 7.0 iframed editor context

WP 7.0 Consideration

With WordPress 7.0's always-iframed editor, PluginPreviewMenuItem components work correctly because they operate at the plugin slot level, not inside the editor canvas iframe. No additional migration needed.

Why this matters for Drupal and WordPress

WordPress theme developers and agencies building client sites need custom preview options for responsive QA and social card validation. The Customizer device hook is especially useful for WordPress shops that must demo exact device widths to clients. The Block Editor Slot/Fill pattern for PluginPreviewMenuItem also shows the extensibility model that Drupal's CKEditor 5 and Layout Builder teams are watching as they design similar plugin-slot APIs for Drupal's editing experience.

What I learned

• The term "editor preview" is ambiguous in WordPress. The Customizer and Block Editor have completely separate extension APIs.
• Customizer: PHP hooks (customize_previewable_devices filter + customize_controls_print_styles action). Simple, no build tools needed.
• Block Editor: React components (PluginPreviewMenuItem via Slot/Fill). Requires @wordpress/scripts and a JavaScript build process.
• useSelect from @wordpress/data is key for creating dynamic, context-aware preview links that respond to the current post's state.

References

• WordPress Developer Resources: customize_previewable_devices filter
• WordPress Developer Resources: customize_controls_print_styles action
• PluginPreviewMenuItem Component Reference
• Official WordPress Block Editor Handbook

---

Looking for an Architect who doesn't just write code, but builds the AI systems that multiply your team's output? View my enterprise CMS case studies at victorjimenezdev.github.io or connect with me on LinkedIn.