Kadence Blocks

Kadence Blocks Template Creation

Produce block markup that pastes into the WordPress editor and validates on the first try. Everything here is verified against Kadence Blocks 3.7.10 on WordPress 7.1.

Read this before generating anything

Kadence markup is unforgiving in one specific way: a static block's saved HTML must match what its save() function would produce, exactly. Get a class name or a wrapper <div> wrong and the editor throws "This block contains unexpected or invalid content" and offers to recover it — which strips the user's styling.

Three rules cover most of the failure surface.

Rule 1 — Know which blocks save HTML and which don't. Dynamic blocks are comment-only; writing HTML inside them makes them invalid. Static blocks require their exact HTML. kadence/rowlayout is dynamic, which surprises people: it has no <div class="wp-block-kadence-rowlayout"> wrapper and no kt-row-column-wrap. Those exist only on the rendered front end.

Rule 2 — Class names are built from uniqueID with no separator, usually. uniqueID abc123 gives kadence-columnabc123. A minority of blocks use a hyphen. Both lists are in reference/save-markup.md. Never put a generated class in className.

Rule 3 — Only use attributes that exist. The editor silently discards unknown attribute names and wrong types, so invented attributes produce markup that validates perfectly and does nothing. Check reference/block-attributes.md — all 62 blocks and 2,705 attributes, generated from the plugin's own manifests.

Rule 4 — Six blocks need "kbVersion":2 or they do not render properly. rowlayout, column, infobox, googlemaps, advancedgallery and testimonials gate their modern PHP render on kbVersion > 1. Omit it and the block still validates in the editor — but on the front end rowlayout emits no wrapper at all, so columns stack, backgrounds vanish and padding is ignored, while testimonials degrades to a bulleted list.

This is the one failure the editor cannot warn you about, because the markup is genuinely valid. The editor sets kbVersion for you when you insert a block through the UI; hand-written markup has to include it.

Do not add kbVersion to any other block. It exists only on those six. On image, advancedbtn, icon, iconlist and everything else it is an unknown attribute, and the editor drops it silently. The linter flags both mistakes — missing where required, present where it is not — so run it rather than trying to remember the list.

Reference files

Pattern files

The block set

Layout

Content

Composite

Attributes you will use constantly

Colors

Kadence themes expose a palette. Use palette1 … palette9 rather than hex so the section follows the site's theme. palette1–palette3 are usually the brand accents, palette4–palette6 neutrals/text, palette7–palette9 backgrounds from dark to light.

"bgColor":"palette9"     row background
"color":"palette4"       text color
"background":"palette1"  button fill

Hex values work too. Mixing them is fine; palette slots just survive a theme change.

Responsive values

Kadence has three conventions and does not use them consistently. Check the attribute table when unsure.

• Three-value arrays [desktop, tablet, mobile] — fontHeight, maxWidth on advancedheading, width on singlebtn.
• Four-value arrays [top, right, bottom, left] — padding, margin, borderRadius.
• Separate attributes per breakpoint — size / tabSize / mobileSize on advancedheading; topPadding / topPaddingM on rowlayout.

There is no tabletSize. It is tabSize. This is the single most common invented attribute.

Row sizing

"align":"full"            edge-to-edge section
"inheritMaxWidth":true    constrain inner content to theme width
"maxWidth":1200           explicit inner width (number, not array)
"topPadding":100          desktop padding, number
"topPaddingM":60          mobile padding
"verticalAlignment":"middle"

uniqueID discipline

Kadence emits one CSS rule per uniqueID. Two blocks sharing an ID share styling, which shows up as "why did changing this section change that one".

• Give every block on the page a distinct uniqueID.
• Real Kadence IDs look like 123_a4b5c6. Readable IDs (hero_h1) work fine and are easier to hand-edit.
• When you paste two examples from these files onto one page, rename the IDs in the second one. The examples deliberately use per-file prefixes to reduce the chance of collision, but they are not globally unique.

Verifying your output

The repo ships the checks used to build it:

python3 tools/lint-attributes.py path/to/markup.html

catches invented attribute names and wrong types — the failures that pass validation but silently do nothing.

python3 tools/extract-examples.py /tmp/all.html

pulls every example in the repo into one file for a single editor round-trip. Validate that file against a real site (the WordPress Studio MCP validate_blocks tool, or paste into an editor and watch for recovery prompts).

python3 tools/extract-schema.py _reference/kadence-blocks

regenerates the attribute reference from a plugin copy. Re-run it after a Kadence update and re-lint; that is how these docs stay honest across versions.

When you are unsure

Prefer the pattern file over improvising. If you need a variant that is not covered:

1. Start from the closest verified pattern.
2. Change only attributes you have confirmed in the attribute table.
3. Leave the save HTML structurally identical unless the attribute you changed is one the table flags as structural (mediaType on infobox, columns on iconlist, paneCount on accordion, tabCount on tabs).
4. Lint, then validate.

Guessing a class name is never safe. Guessing an attribute name is worse, because nothing will tell you it was wrong.