Pseudo and custom style states land in 7.1

Pseudo states

In WordPress 7.1, users have more power over styling the pseudo states of blocks. Currently limited to the Button and Navigation Link blocks, users are able to apply styles to ‘hover’, ‘focus’, ‘focus-visible’ and ‘active’ states.

Pseudo states support definitions in theme.json for themers, and block styling in global styles and on block instances for users.

Defining pseudo states for blocks in theme.json

Define pseudo states within the block object using the properties “:hover”, “:focus”, “:focus-visible”, and “:active”. Pseudo state names are always prefixed with a :.

"styles": {
	"blocks": {
		"core/button": {
			"color": {
				"background": "black",
				"text": "white"
			},
			":hover": {
				"color": {
					"background": "blue"
				}
			},
			":focus": {
				"color": {
					"background": "purple"
				}
			}
		}
	}
}

Pseudo states can also be nested within responsive states:

"styles": {
	"blocks": {
		"core/button": {
			"@mobile": {
				":hover": {
					"color": {
						"background": "var:preset|color|contrast",
						"text": "var:preset|color|base"
					}
				}
			}
		}
	}
}

Block instance attributes

The structure for block instance attributes is very similar to the theme.json definition with :hover properties used inside the style attribute:

<!-- wp:button {"backgroundColor":"accent-3","style":{":hover":{"color":{"background":"var:preset|color|accent-2"}}}} -->
<div class="wp-block-button"><a class="wp-block-button__link has-accent-3-background-color has-background wp-element-button">Button with pseudo state background</a></div>
<!-- /wp:button -->

Custom style states

Custom states are an early feature limited to theme.json definition only (no user facing features are exposed) and only the navigation link block. The navigation block uses this to allow styling of the current menu item – that is the menu item whose link matches that of the currently viewed page.

Defining custom states for the navigation link block in theme.json

Styles for the current menu item can be defined using the -current property. Custom states always use the -prefix.

"styles": {
	"blocks": {
		"core/navigation-link": {
			"-current": {
				"color": {
					"text": "var:preset|color|contrast"
				},
				":hover": {
					"color": {
						"text": "var:preset|color|accent-1"
					}
				}
			}
		}
	}
}

As shown above, pseudo states can be nested within custom states. Custom states can also be nested within responsive states.

Style generation

The styles defined for custom states generate css that targets a class name selector. For the navigation link block, that would expand to something like .wp-block-navigation-link .current-menu-item { // styles ... }.

The styles css class name that’s generated in the selector would be declared on supported blocks via a block’s block.json selectors property:

"selectors": {
	"states": {
		"-current": ".wp-block-navigation-link .current-menu-item"
	}
}

Opting out of style state editing

Sites can prevent users from styling block states via the blockStatesEditingEnabled editor setting:

function example_disable_block_states_editing( $settings ) {
	$settings['blockStatesEditingEnabled'] = false;
	return $settings;
}
add_filter( 'block_editor_settings_all', 'example_disable_block_states_editing' );

blockStatesEditingEnabled defaults to true.

When it is false, both the state dropdown in the block inspector’s block card, and the pseudo state options in the “States” dropdown in Global Styles under Styles > Blocks are hidden.

The states affected are the pseudo states, Hover, Focus, Focus-visible and Active, which currently apply to the Button and Navigation Link blocks. In the future this will extend to other states present in the dropdown, like the ability for users to set styles for the Navigation Link’s ‘Current’ state.

This setting does not affect viewport states. Those are controlled separately by responsiveEditingEnabled. Set both to false to remove the state editing interface entirely.

The setting governs the editing interface only. State styles already saved in theme.json, in Global Styles, or in a block’s style attribute are left untouched and are still applied, so existing content renders exactly as before both in the Editor and on the front end.

Reviewed by @ramonopoly, @andrewserong; props @wildworks

#7-1, #dev-notes, #dev-notes-7-1