Server-Side Rendering for WordPress Blocks, Explained

Server-side rendering generates a WordPress block’s frontend HTML during a request. PHP receives saved attributes and returns current markup. The database may store only a delimiter comment.

This architecture suits changing data, shared markup, and server-only logic. Examples include latest posts, query results, login states, and calculated values.

It also creates a runtime dependency. The provider must remain active for output. Rendering code must be fast, secure, cache-aware, and backward-compatible.

Server rendering in one request

1. Parse

Read the saved block and attributes.

2. Render

Call registered PHP with current context.

3. Return

Receive escaped frontend HTML.

4. Deliver

Combine it with the complete page.

A minimal dynamic block

{
  "apiVersion": 3,
  "name": "acme/current-year",
  "title": "Current Year",
  "category": "widgets",
  "render": "file:./render.php"
}

<?php
$wrapper = get_block_wrapper_attributes();
echo sprintf(
    '<time %s>%s</time>',
    $wrapper,
    esc_html( wp_date( 'Y' ) )
);

The metadata points toward a PHP template. WordPress loads it during rendering. The output changes with the server date without resaving content.

Dynamic rendering and ServerSideRender differ

Dynamic rendering describes how frontend HTML is produced. The ServerSideRender package requests PHP output for an editor preview. These concepts overlap but remain distinct.

A dynamic block can build a native editor interface without server previews. It can fetch structured data through REST APIs. The frontend still renders through PHP.

Likewise, an editor preview does not define database storage alone. Saving strategy remains separate. Avoid treating one component as the whole architecture.

When server-side rendering fits

• Output depends on current database records.
• Markup must change everywhere after one code update.
• Visibility depends on the current user or request.
• Existing PHP APIs already own the business logic.
• Results require permissions unavailable to browser code.
• A query must reflect current dates or publication states.
• Server filters must alter output consistently.

Use dynamic output because data or context changes. Do not choose it merely because PHP feels familiar. Static blocks are simpler for stable content.

When static saving fits better

Static saving works well for authored text, images, notices, and fixed layouts. The content becomes durable HTML inside post_content.

Visitors need no rendering callback for that markup. Caches receive straightforward output. Plugin deactivation can leave visible content behind.

Static blocks do require markup compatibility. Changing the saving function can invalidate older instances. Deprecations manage that evolution.

Our static versus dynamic guide compares broad tradeoffs. This article covers the server implementation in detail.

What save returning null means

Many dynamic blocks return null from their saving function. WordPress then stores no inner HTML for that block. Attributes remain inside its delimiter comment. We cover the method in caching dynamic WordPress blocks safely.

<!-- wp:acme/latest-items {"count":6} /-->

The compact representation avoids static markup validation. PHP owns current output entirely. Updating rendering code changes every instance immediately.

That convenience has a weak case. Deactivating the provider leaves no saved fallback HTML. The visible block can disappear until registration returns.

Dynamic blocks can save fallback HTML

A dynamic block may save an HTML representation too. Registered PHP replaces that content during normal rendering. Saved HTML remains available when rendering disappears.

The official dynamic-block guide documents this fallback. It can preserve a last-known or authored representation after deactivation.

A fallback is not always accurate. Query results become stale. Permission-specific content could become unsafe. Decide which representation remains acceptable publicly.

Saving HTML also restores validation responsibilities. Current saving output must recognise historical markup. Maintain deprecations when its structure changes.

InnerBlocks must remain serialized

A dynamic container can hold nested blocks. Those children need saved block markup. Its saving function should output InnerBlocks.Content where appropriate.

The server callback receives rendered inner content. It can wrap or conditionally place that content. It should not discard authored children unexpectedly.

Returning null for a container can lose its nested serialization. Test saving, reopening, duplicating, and deactivation with realistic child structures.

Register rendering through metadata

Modern blocks can declare a render file inside block.json. Plugins register the metadata directory through register_block_type().

A plugin can also provide a callable render_callback during registration. That callback can override metadata rendering. Keep ownership obvious for maintainers.

Metadata keeps attributes, assets, supports, and rendering near one contract. The server must register the block. Client-only registration cannot execute PHP output.

Use the built directory in production. Confirm the package includes render.php. Missing files can turn registered blocks into empty output.

What the rendering callback receives

Rendering callbacks receive parsed attributes. They can also receive inner content and a block instance. Exact signatures depend on the registration approach.

The block instance can expose context from ancestor blocks. Query-related children may use inherited post identifiers. Context should have safe missing-value behaviour.

Attributes reflect saved content, not trusted configuration. Validate their types and allowed values. Apply defaults consistently with the registered schema.

Use the server wrapper helper

get_block_wrapper_attributes() supplies generated wrapper classes and styles. It connects server output with standard block supports. Omitting it can break user settings.

Pass suitable extra attributes through the helper. Escape any separately generated values for their HTML context. Avoid hand-building class strings from raw input.

The helper belongs on the primary block wrapper. Complex inner selectors may handle supported styles elsewhere. Test editor and frontend parity for every support.

Escape output at the final context

Dynamic rendering runs on every uncached request. Stored attributes can contain untrusted input. Database results can also include unsafe values.

• Escape plain text with the suitable text helper.
• Escape URLs before placing them into attributes.
• Escape HTML attributes with the attribute helper.
• Allow restricted HTML only through explicit policies.
• Check capabilities before exposing private records.
• Use nonces for state-changing editor requests.

Sanitisation and escaping solve different moments. Sanitize when accepting data. Escape when emitting it into a known context.

Queries need explicit limits

A rendering callback can query posts, terms, users, or custom records. Every query needs bounded counts and suitable indexes. User attributes should not create unlimited work.

A count control may accept six. Validate its minimum and maximum. Never pass an arbitrary request value directly into an expensive query.

Avoid repeated identical queries across instances. Shared caches or preloading can help. Measure database time on pages containing several blocks.

Caching dynamic block output

Full-page caching can absorb most rendering costs for public pages. Fragment caching can help expensive blocks. Object caching can reuse underlying query results.

Cache keys must include every output-changing input. Attributes, locale, permissions, query context, and relevant records can matter. Missing dimensions leak incorrect output.

Invalidation is the difficult part. Time-based expiry accepts temporary staleness. Event-based invalidation needs reliable hooks for every dependency.

Do not cache personalised output globally. Separate public and private variants. Verify behaviour while logged in and logged out.

Editor previews have three common approaches

Approach	Strength	Weak case
Native edit UI	Fast and directly editable	Can differ from PHP markup
Structured REST data	Flexible and responsive	Duplicates presentation logic
ServerSideRender	Exact PHP preview	Network-bound and less interactive

ServerSideRender is a fallback tool

The ServerSideRender package reference describes editor previews from PHP. It sends attributes through a REST request and returns HTML.

The package handles loading, errors, and request debouncing. POST supports larger attribute payloads. The output still comes from the registered rendering callback.

Official guidance treats this approach as a fallback for legacy server logic. Structured endpoints usually create better editor manipulation. They avoid refreshing whole preview fragments.

Use server previews when reproducing PHP output would be unreasonable. Provide clear loading and error states. Never leave editors staring at an empty box.

Interactive frontend behaviour remains separate

PHP can generate initial HTML. Frontend JavaScript may enhance that output afterward. Server rendering alone does not provide client interaction.

Progressive enhancement keeps essential content available before scripts run. Buttons and forms need semantic initial markup. Loading failures should preserve basic meaning.

Declare frontend assets through block metadata where suitable. Load them only when needed. Avoid attaching large interaction bundles to static informational blocks.

Deactivation changes dynamic output

When the provider deactivates, WordPress loses its registered callback. A comment-only block then contributes no generated HTML. Saved fallback markup can remain visible.

The content still exists inside post_content. Reactivating the provider can restore rendering. Avoid converting missing blocks before testing restoration.

Run the full block-plugin deactivation test on staging. Record frontend, editor, and reactivation behaviour separately.

Rendering outside normal page views

Block rendering can occur through feeds, REST responses, excerpts, previews, and administrative requests. The callback should not assume one frontend template.

Global query state may differ across those contexts. Request objects may be unavailable. Build output from explicit attributes and reliable WordPress APIs.

Relative links can resolve differently in syndicated content. Interactive controls may make little sense inside feeds. Provide useful semantic output first.

Search indexing also receives rendered HTML. Avoid hiding essential text behind client-only requests. Current server output should remain crawlable and meaningful.

Observability for rendering callbacks

Production failures can affect every instance immediately. Record callback exceptions through normal application logging. Never print debugging details into public markup.

Measure callback duration and query counts under representative load. Track cache hit rates where possible. A fast empty test proves very little.

Return safe fallback output after recoverable failures. An accessible notice may help administrators. Visitors usually need quieter behaviour and preserved page structure.

Monitor after dependency updates. A changed API response can break rendering without editing content. Shared callbacks amplify upstream changes across the site.

Common server-rendering failures

• The block was never registered on the server.
• The release package omitted its rendering file.
• Saved attributes no longer match expected types.
• The callback returns output instead of the intended string.
• Wrapper attributes are missing or applied twice.
• A query runs without limits on every request.
• Private data reaches a public cache.
• Editor preview requests fail authentication or validation.
• A missing context value causes a fatal error.
• Fallback HTML exposes stale or inappropriate information.

A blank frontend block is usually a registration or callback problem. A blank editor preview can be separate. Inspect both request paths.

A debugging sequence

1. Confirm the server knows the registered block type.
2. Inspect the saved delimiter and attributes.
3. Call rendering with a minimal known fixture.
4. Log exceptions without exposing them publicly.
5. Verify callback output is a string.
6. Check wrapper classes and support styles.
7. Profile queries and repeated callback calls.
8. Disable caches while isolating the problem.
9. Test editor preview requests independently.
10. Restore normal caching and verify again.

Build one deterministic fixture before testing live data. It separates rendering logic from changing queries. Then add request context gradually.

A production readiness checklist

• Register metadata on both server and client.
• Validate every saved attribute before use.
• Escape every value for its output context.
• Apply block wrapper attributes once.
• Bound queries and measure repeated instances.
• Define cache keys and invalidation rules.
• Protect personalised output from public caches.
• Provide meaningful editor loading and error states.
• Test saved fallback behaviour after deactivation.
• Keep fixtures for historical attribute shapes.
• Monitor errors and slow queries after release.

Server rendering centralises output changes. That power expands the blast radius. Test one callback like shared production infrastructure, because it is.

Frequently asked questions

The verdict

Dynamic features can justify a provider dependency. Simple content rarely needs one. Test every free WP Block Suite plugin on staging first. Then compare the $299 lifetime suite when multiple Pro features earn their runtime cost.