WordPress 7.0 introduces the ability to add custom CSS Cascading Style Sheets. directly to individual block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. instances from within the post and site editors. This closes a long-standing gap in the block styling system: while Global Styles has supported block-type-level custom CSS since WordPress 6.2, there was no built-in way to target a single specific block on a specific page without a multi-step workaround.
GitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ issue: #56127 | PR: #73959
The Problem
Previously, applying one-off CSS to a specific block instance required a workaround: add a custom class name to the block, then write a matching rule in the Site Editor’s global Custom CSS field. This two-step process was not obvious to most users, and was entirely unavailable to content editors who lack access to the Site Editor.
Plugins emerged to fill this gap, confirming genuine demand for the feature.
What Changed
A new customCSS block support is registered. It provides a Custom CSS input inside the Advanced panel of the block inspector — the same panel that already contains the “Additional CSS Class(es)” field.
The panel behaves the same way as the block-type custom CSS field in Global Styles:
- Only CSS declarations are needed — no selector is required.
- Nested selectors can be written using
& (e.g., & a { color: red; } targets anchor tags inside the block).
- HTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. markup in the CSS field is rejected.
- The field is only visible to users with the
edit_css capability A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability)..
How It Works
Storage
Custom CSS is stored in the block’s existing style attribute, under the css key — the same attribute that stores other block-level style overrides:
<!-- wp:heading {"level":6,"style":{"css":"color: blue;\n"}} -->
<h6 class="wp-block-heading has-custom-css">Heading</h6>
<!-- /wp:heading -->
Frontend Output
At render time, a unique class is generated for the block instance using a hash of the block’s content and attributes. The class is applied to the block’s outermost HTML element alongside a has-custom-css marker class:
<h6 class="wp-block-heading has-custom-css wp-custom-css-8841bf3c3cc97689d62771455cc88782">
Heading
</h6>
<style id="wp-block-custom-css">
:root :where(.wp-custom-css-8841bf3c3cc97689d62771455cc88782) {
color: blue;
}
</style>
The generated stylesheet is registered with a dependency on global-styles, ensuring block instance CSS loads after — and can therefore override — both WordPress defaults and Global Styles block-type CSS.
Editor Preview
The custom CSS is also applied live in the editor using a scoped style override, so changes are reflected immediately without saving.
Opt-Out
The customCSS support is enabled by default for all blocks. Block authors who need to opt out — for example, blocks that render raw content or have no meaningful outer element — can disable it in block.json:
{
"supports": {
"customCSS": false
}
}
The following core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks opt out by default: core/freeform, core/html, core/missing, core/more, core/nextpage, core/shortcode, and core/block (the Reusable Block wrapper).
Capability Check
The Custom CSS panel is gated by the edit_css capability. Users without it will not see the field in the block inspector. This is the same capability used to control access to the Custom CSS field in the Customizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. and in Global Styles.
For Plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. and Theme Developers
No action is required for most blocks and themes. The support is enabled automatically.
If you maintain a block that should not expose a custom CSS input — because it wraps raw or opaque content, or because adding a class to its root element would break its rendering — add "customCSS": false to your block’s supports in block.json.
If you render blocks server-side using render_callback or render in block.json, the class will be injected into the first HTML element in the rendered output via WP_HTML_Tag_Processor. Ensure your block renders a standard HTML element as its outermost tag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.).
Further Reading
Props to @mtias and @glendaviesnz for the implementation, @aaronrobertshaw and @scruffian for technical review and proofreading.
#7-0, #dev-notes, #dev-notes-7-0
