Skip to content
← All guidesWordPress & Gutenberg

Gutenberg custom blocks explained: what WordPress stores and renders

Understand block definitions, attributes, saved markup and dynamic rendering before choosing how to build a custom Gutenberg block.

A block is more than the HTML you see

In the editor, a Gutenberg block combines a registered block type, an editing interface, attributes that represent content or settings, and a strategy for producing front-end output. Thinking of a block as only a chunk of HTML makes later decisions about validation, migrations and dynamic data much harder.

The block type defines the contract. It gives WordPress a stable name, supported features and an attribute schema. The editor uses that contract to turn user interactions into structured values. The front end then renders those values either from saved markup or through server-side logic.

Attributes are the block’s stored state

Attributes hold the values that make one instance of a block different from another: heading text, selected image, alignment, colour choice or a list of items. A clear attribute model makes the editor easier to reason about and reduces the temptation to infer important data from arbitrary markup.

Choose attribute shapes that match the content concept. A collection of repeated items is easier to maintain as structured data than as one large HTML string. Defaults should be useful but should not hide whether the user has made an explicit choice.

Static and dynamic blocks solve different problems

A static block saves the front-end markup produced by its save implementation into post content. This can be efficient and portable, but changes to the expected markup need to consider validation and deprecation paths for existing content.

A dynamic block stores the block comment and attributes while generating the visible output on the server when the page is rendered. Dynamic rendering is useful when the output depends on current site data or when you want to change presentation logic without rewriting every saved post.

Editor experience and front-end output can differ

The editor does not need to reproduce every front-end behaviour exactly. It needs to give authors enough context to edit confidently. Complex queries, animation or expensive rendering can often be represented with a simpler preview while the front-end output remains fully featured.

Design the content model before the controls

Before adding inspector panels and toolbar buttons, write down the information the block must represent. Decide what belongs in content, what is presentation, and what should inherit from the theme. A block with a small, stable data model is easier to style, migrate and reuse across a site.

Start with the content model. The editor controls are an interface for that model, not the model itself.
This guide is general educational content. Project, contractual, tax and legal requirements can vary, so check the requirements that apply to your work before relying on a particular approach.