Guide

Dialog

Render content in a modal dialog. Includes a trigger to open the dialog and a dialog element (<dialog/>) to display content.

Block Metadata

PropertyValue
Namespaceprc-block/dialog
Categorymedia
Version1.1.0
API Version3
Keywordsdialog, modal, popup
ExampleYes (with inner blocks — drives inserter preview)

Supports

FeatureValue
Anchorfalse
HTML editingfalse
List Viewtrue
Font sizetrue (default controls enabled)
Font familytrue (default controls enabled)
Interactivitytrue

Attributes

AttributeTypeDefaultRoleDescription
dialogIdstring""—Unique identifier for the dialog. Defaults to the block's clientId in the editor. Must be unique on the page.
editorIsDialogOpenbooleanfalselocalEditor-only state tracking whether the dialog content is currently visible for editing. Not saved to post content.

Provided Context

Context KeySource Attribute
dialog/iddialogId
dialog/isOpeneditorIsDialogOpen

Allowed Inner Blocks

  • prc-block/dialog-element
  • prc-block/dialog-trigger

Inner Blocks Template

The block initializes with a locked template:

  1. Dialog Trigger (prc-block/dialog-trigger) — Contains a paragraph for trigger text.
  2. Dialog Element (prc-block/dialog-element) — Contains a heading bound to the dialog label.

Template lock is set to insert (blocks cannot be added/removed, but content can be edited).

Parent/Ancestor Requirements

None. This is the top-level container for dialog functionality.

Usage Instructions

  1. Insert the Dialog block from the block inserter (under the Media category, or search for "dialog", "modal", or "popup").
  2. Type trigger text in the Dialog Trigger area — this is what users will click to open the dialog.
  3. Click "Edit Dialog" in the block toolbar or inspector panel to reveal the dialog element for editing.
  4. Add content inside the Dialog Element (headings, paragraphs, images, etc.).
  5. Click "Close Dialog" to return to the trigger view.
  6. The Dialog ID can be customized in the inspector panel. It must be unique on the page.
  7. The dialog auto-opens for editing when you select the dialog element or its inner blocks.

Note: Editor inspector controls were updated for current WordPress component defaults (removed obsolete __next40pxDefaultSize props).

Block Markup Example

The example defined in block.json drives the inserter preview. It uses a bare dialog-trigger (no inner content) and a dialog-element with medium size and fade animation:

<!-- wp:prc-block/dialog {"dialogId":"123"} -->
<!-- wp:prc-block/dialog-trigger /-->
<!-- wp:prc-block/dialog-element {"dialogSize":"medium","animation":"fade"} /-->
<!-- /wp:prc-block/dialog -->

A more complete real-world example with inner content:

<!-- wp:prc-block/dialog {"dialogId":"my-dialog"} -->
<!-- wp:prc-block/dialog-trigger -->
<!-- wp:paragraph -->
<p>Click to open</p>
<!-- /wp:paragraph -->
<!-- /wp:prc-block/dialog-trigger -->

<!-- wp:prc-block/dialog-element {"dialogSize":"medium","animation":"fade"} -->
<!-- wp:heading -->
<h2>Dialog Title</h2>
<!-- /wp:heading -->
<!-- /wp:prc-block/dialog-element -->
<!-- /wp:prc-block/dialog -->

PHP Rendering

The Dialog PHP class provides a server-side render callback:

  1. Requires a dialogId attribute. If missing, outputs a _doing_it_wrong warning and returns empty.
  2. A render_block_data filter provides a fallback: if no dialogId is set, it generates one via wp_unique_id('dialog-').
  3. Wraps inner content in a <div> with Interactivity API directives: data-wp-interactive="prc-block/dialog", data-wp-context (containing the dialog ID), and data-wp-key.

Rendered output:

<div
	class="wp-block-prc-block-dialog"
	data-wp-interactive="prc-block/dialog"
	data-wp-context='{"id":"my-dialog"}'
	data-wp-key="my-dialog"
>
	<!-- trigger and dialog element content -->
</div>

Frontend Interactivity

The Dialog block itself serves as the container. The actual interactivity logic lives in the prc-block/dialog-element view script (see dialog-element.md). The dialog block establishes the Interactivity API context that its children consume.

Was this helpful?