WordPress block markup reference

Caity

This page aims to document the WordPress (WP) tag markup used in WP block themes. It will no doubt remain incomplete for a long time, but I will fill it in as best I can. I’ve only added the keys and values I’ve seen in use in other themes or have used myself, either programmatically or reverse-engineered from looking at the code produced by the WP visual editor.

The WP Classic block appears to have no special coding; it’s merely plain HTML.

WordPress block markup

Numerical values are typically integers and true/false values are typically booleans; neither needs quotes. All other values are strings and require double quotes (").

WordPress block markup
Block name Key Value
<any (block-based) tag> className e.g. post-meta, is-post-content
gradient e.g. red-to-green
layout* See table of complex values
style* See table of complex values
<any text-based tag> fontSize e.g. medium, 12px, normal
textAlign center
textColor e.g. foreground
typography* See table of complex values
wp:button
wp:buttons
wp:code
wp:column verticalAlignment top
center
width e.g. 46.67%
wp:columns isStackedOnMobile false
wp:gallery imageCrop false (boolean)
linkTo none
wp:heading level 1 (integer)
2 (integer)
3 (integer)
4 (integer)
5 (integer)
6 (integer)
wp:image align center
height e.g. 214 (integer)
id e.g. 12 (integer)
linkDestination none
sizeSlug large
full
style* See table of complex values
width e.g. 214 (integer)
wp:list ordered true (boolean)
wp:navigation className e.g. navigation-main
isResponsive true
setCascadingProperties true
showSubmenuIcon false
openSubmenusOnClick true
false
overlayBackgroundColor e.g. dark, primary, background
overlayMenu never
always
mobile
overlayTextColor e.g. white
navigationMenuId e.g. 12 (integer)
flexWrap wrap
ref e.g. 216 (integer)
showSubmenuIcon true
type flex
__unstableLocation† primary‡
__unstableSocialLinks† social
wp:navigation-link
wp:navigation-submenu		 label e.g. Home, About, Blog, Privacy Policy
url (url)
kind custom
post-type
isTopLevelLink true
false
type page
title e.g. Home, About, Blog, Privacy Policy
id e.g. 223 (integer)
wp:page-list isNavigationChild true
openSubmenusOnClick true
false
wp:paragraph align center
fontSize e.g. m
textColor e.g. electric-violet
style* See table of complex values
wp:post-author showAvatar false
avatarSize e.g. 24, 45, 96 (integer)
showBio false
true
byLine e.g. By, Published by
wp:post-date
wp:post-excerpt
wp:post-featured-image
wp:post-title		 isLink true
wp:post-navigation-link className e.g. post-nav-link
type previous
next
label e.g. Previous post, Next post
wp:preformatted
wp:pullquote Inserts a figure HTML tag
wp:query queryId e.g. 1 (integer)
query* See table of complex values
wp:query-title type archive
wp:quote
wp:search label e.g. Search
buttonText e.g. Search
buttonPosition button-inside
buttonUseIcon true
showLabel false
wp:site-logo className e.g. site-logo
shouldSyncIcon true
wp:table Inserts a figure HTML tag
hasFixedLayout true (boolean)
style* border
borderColor
className
fontSize
wp:template
wp:template-part
wp:group		 tagName e.g. main, div
wp:template-part slug footer
header
area footer
header
wp:terms term category
post_tag
wp:verse

*The values of these markup keys are complex: they are keys themselves; see below.

†I don’t know what the significance of the initial double underscore is.

‡I suspect this is the name of a menu position, but I’m not sure.

Complex values

The following table shows the values of the complex values listed above. Values are strings unless otherwise indicated.

The values of the complex values from the table of WordPress block markup
Complex value Key Value
border style solid
width 2px
layout inherit true
justifyContent center
right
left
orientation horizontal
vertical
setCascadingProperties true
type flex
margin top
bottom
left
right		 (as in CSS/HTML)
padding top
bottom
left
right		 (as in CSS/HTML)
query perPage e.g. 5 (integer)
offset e.g. 0 (integer)
pages e.g. 0 (integer)
postType post
categoryIds [] (array)
tagIds [] (array)
order desc
orderBy date
author
search
exclude [] (array)
sticky
inherit true
typography letterSpacing e.g. 0.13em
lineHeight e.g. 1 (string)
style spacing margin
color* {}
elements* {}

Usage

The keys and values are inserted into the markup tags as JSON. They can be used in both the parts HTML files and the templates HTML files.

<!-- wp:block-name {
  "key-a":"value-a",
  "key-b":"value-b"
} /-->
<!-- wp:block-name {
  "key-a":{
    "key-a-a":"value-a-a",
    "key-a-b":"value-a-b
  },
  "key-b":"value-b"
} /-->

Examples

The above usage is probably unclear, so here’s some examples to clarify:

<!-- wp:navigation {
  "isResponsive":"true"
} /-->
<!-- wp:navigation {
  "isResponsive":"true",
  "layout":{
    "type":"flex",
    "justifyContent":"center"
  }
} /-->

Complex examples

Some uses are too nested to be indicated clearly in the above tables. Here is an example:

<!-- wp:paragraph {
  "style":{
    "elements":{
      "link":{
        "color":{
          "text":"var:preset|color|background-secondary"
        }
      }
    }
  },
  "backgroundColor":"font-tertiary",
  "fontSize":"xl"
} -->
<p>The quick brown fox jumped over the lazy dog.</p>
<!-- /wp:paragraph -->

I can only guess at what the vertical bar | means.

Wait, there’s more!