WordPress block markup reference

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 nameKeyValue
<any (block-based) tag>classNamee.g. post-meta, is-post-content
gradiente.g. red-to-green
layout* See table of complex values
style* See table of complex values
<any text-based tag>fontSizee.g. medium, 12px, normal
textAligncenter
textColore.g. foreground
typography* See table of complex values
wp:button
wp:buttons
wp:code
wp:columnverticalAlignmenttop
center
widthe.g. 46.67%
wp:columnsisStackedOnMobilefalse
wp:galleryimageCropfalse (boolean)
linkTonone
wp:headinglevel1 (integer)
2 (integer)
3 (integer)
4 (integer)
5 (integer)
6 (integer)
wp:imagealigncenter
heighte.g. 214 (integer)
ide.g. 12 (integer)
linkDestinationnone
sizeSluglarge
full
style* See table of complex values
widthe.g. 214 (integer)
wp:listorderedtrue (boolean)
wp:navigationclassNamee.g. navigation-main
isResponsivetrue
setCascadingPropertiestrue
showSubmenuIconfalse
openSubmenusOnClicktrue
false
overlayBackgroundColore.g. dark, primary, background
overlayMenunever
always
mobile
overlayTextColore.g. white
navigationMenuIde.g. 12 (integer)
flexWrapwrap
refe.g. 216 (integer)
showSubmenuIcontrue
typeflex
__unstableLocationprimary
__unstableSocialLinkssocial
wp:navigation-link
wp:navigation-submenu
labele.g. Home, About, Blog, Privacy Policy
url(url)
kindcustom
post-type
isTopLevelLinktrue
false
typepage
titlee.g. Home, About, Blog, Privacy Policy
ide.g. 223 (integer)
wp:page-listisNavigationChildtrue
openSubmenusOnClicktrue
false
wp:paragraphaligncenter
fontSizee.g. m
textColore.g. electric-violet
style* See table of complex values
wp:post-authorshowAvatarfalse
avatarSizee.g. 24, 45, 96 (integer)
showBiofalse
true
byLinee.g. By, Published by
wp:post-date
wp:post-excerpt
wp:post-featured-image
wp:post-title
isLinktrue
wp:post-navigation-linkclassNamee.g. post-nav-link
typeprevious
next
labele.g. Previous post, Next post
wp:preformatted
wp:pullquote Inserts a figure HTML tag
wp:queryqueryIde.g. 1 (integer)
query* See table of complex values
wp:query-titletypearchive
wp:quote
wp:searchlabele.g. Search
buttonTexte.g. Search
buttonPositionbutton-inside
buttonUseIcontrue
showLabelfalse
wp:site-logoclassNamee.g. site-logo
shouldSyncIcontrue
wp:table Inserts a figure HTML tag
hasFixedLayouttrue (boolean)
style*border
borderColor
className
fontSize
wp:template
wp:template-part
wp:group
tagNamee.g. main, div
wp:template-partslugfooter
header
areafooter
header
wp:termstermcategory
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 valueKeyValue
borderstylesolid
width2px
layoutinherittrue
justifyContentcenter
right
left
orientationhorizontal
vertical
setCascadingPropertiestrue
typeflex
margintop
bottom
left
right
(as in CSS/HTML)
paddingtop
bottom
left
right
(as in CSS/HTML)
queryperPagee.g. 5 (integer)
offsete.g. 0 (integer)
pagese.g. 0 (integer)
postTypepost
categoryIds[] (array)
tagIds[] (array)
orderdesc
orderBydate
author
search
exclude[] (array)
sticky
inherittrue
typographyletterSpacinge.g. 0.13em
lineHeighte.g. 1 (string)
stylespacingmargin
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.