Both the Gutenberg block editor and the visual builder include live preview capabilities. The preview renders your sections in a sandboxed iframe that loads your theme’s stylesheets, giving you an accurate representation of how the page will look.
How the Preview Works
The preview constructs a full HTML document and sets it as the iframe’s srcdoc. The document includes, in order.
- Theme stylesheet
<link>tags. - Theme inline styles (global styles, classic theme styles).
- Preview injection head HTML (if configured).
- A helper CSS rule that hides sticky share widgets.
- Injected CSS from the preview injection filter.
- Section CSS combined into a
<style>tag. - Head JavaScript from the preview injection filter.
- Inline JavaScript from sections with jsLocation set to “inline”.
- Body start HTML from the preview injection filter.
- Section HTML content.
- Theme scripts (jQuery, theme JS files).
- Footer JavaScript from the preview injection filter.
- Footer JavaScript from sections with jsLocation set to “footer”.
- Body end HTML from the preview injection filter.
Theme Asset Collection
The visual builder automatically discovers and loads your theme’s CSS and JavaScript files into the preview.
Stylesheets
The builder collects theme stylesheets from three sources.
Explicit theme styles. The child theme’s style.css and parent theme’s style.css are always included. Additionally, any CSS files found in the theme’s css/ and assets/css/ directories (recursively) are included.
Page stylesheets. Any <link rel="stylesheet"> tags on the builder page whose URLs match the theme directory are collected.
Inline styles. Any <style> tags with IDs containing “global-styles”, “classic-theme-styles”, or starting with “theme” are collected.
Scripts
Theme JavaScript files and jQuery (from wp-includes/js/jquery/) are collected from the page’s script tags and included in the preview.
Client-Side vs. Server-Side Preview
The preview uses two rendering modes depending on section settings.
Client-Side Preview
When no section has format or phpExec enabled, the preview is built entirely in the browser. The raw HTML, CSS, and JavaScript from your sections are assembled into the preview document without any server request. This is instant.
Server-Side Preview
When any section has format or phpExec enabled, the builder sends the sections to the md_page_blocks_builder_preview AJAX endpoint. The server processes the content (executing PHP, applying the_content filter) and returns the rendered output as JSON.
POST /wp-admin/admin-ajax.php
action=md_page_blocks_builder_preview
post_id=123
pb_nonce=abc123
sections=[{"content":"...","css":"...","js":"...","format":true,"phpExec":false}]The response contains.
{
"success": true,
"data": {
"html": "rendered HTML output",
"css": "minified CSS",
"jsInline": "inline JavaScript",
"jsFooter": "footer JavaScript"
}
}The builder then inserts this rendered output into the preview document in place of the raw section content.
Preview Debouncing
In the visual builder, preview updates are debounced by 110ms. This means rapid typing doesn’t trigger a preview rebuild for every keystroke. The preview is only rebuilt 110ms after you stop typing.
In the Gutenberg block editor, the preview updates reactively when block attributes change, using React’s effect system.
Preview Request Tracking
Both the visual builder and the Gutenberg block use request ID tracking to prevent stale responses. Each preview request increments a counter. When the response arrives, it checks whether the counter has advanced (meaning a newer request was made). If it has, the stale response is discarded.
Viewport Controls
The visual builder’s preview canvas includes viewport control buttons.
- Desktop renders the preview at full width (no constraint).
- 992 constrains the preview iframe to 992px wide.
- 768 constrains to 768px.
- 480 constrains to 480px.
- 360 constrains to 360px.
The iframe resizes to the selected width with max-width: calc(100% - 24px) to maintain a small margin. The active viewport button is highlighted.
Collapsed Sections
In the visual builder, sections can be “collapsed” (hidden from the preview). Collapsed sections are excluded from the preview document but are still saved when you apply to Gutenberg. This lets you temporarily hide sections to focus on specific parts of the page during development.
Preview in Gutenberg
The Gutenberg block editor also supports preview mode for individual Page Blocks. Click the eye icon on a block’s toolbar to switch to preview mode. The block shows an iframe with the rendered output, including theme stylesheets. Click the pencil icon to return to editor mode.
When format or phpExec is enabled on the block, the Gutenberg preview also uses server-rendered content via the same AJAX endpoint.