Extending the Custom CSS editor

With the Custom CSS project merging into WordPress Core, some of y’all may be looking to extend it and do more advanced stuff.  Maybe you help run an existing plugin (like me) that has already provided a Custom CSS input to WordPress core and you’re now looking to migrate that data over.  Or maybe you want to change how it outputs.  Here’s what I’ve found so far in my work converting Jetpack’s Custom CSS module to be an enhancement layer on top of the Core implementation, providing legacy feature parity.

Disclaimer: This is just what I’ve found to be useful so far, the Jetpack update is still a work in progress as I write this.

Data Structure

Core’s data store is in a Custom Post Type named custom_css, and the CSS is stored in the post_content.  It sets up a new post for each theme’s custom css, and only the active theme’s one is used.  There’s no accounting for parent/child themes — it uses the slug from the current stylesheet (child theme) as the post_name; that is, Custom CSS lookups are indexed by the return value of get_stylesheet().  Core does not yet have have a UI for displaying the revisions for changes to Custom CSS or a way display the saved Custom CSS of inactive themes, but revisions are enabled on the post type, so no data is lost until the revision viewer makes its way into core (or the user activates a plugin that provides similar functionality). Follow #31089 for more on revisions in the customizer, for all settings not just for Custom CSS.

Getting The Custom CSS

The generated CSS itself can be gotten via the wp_get_custom_css() function, which just returns the CSS for the current theme as a string. This function is used in the wp_head callback when the CSS is printed into a style tag.  One of the more useful functions in the Core implementation for advanced development is wp_get_custom_css_post( $stylesheet = '' ) — this will return either null or the WP_Post object if the site has any Custom CSS saved for the current site.  If you’re building a custom revision viewer, this will be the post you’ll key off of to fetch the revisions.

Filters on Read and Update

The wp_get_custom_css() function applies a wp_get_custom_css filter to the styles just before they’re returned.  This allows for targeted tweaks such as minifying the output on the front-end before it’s echoed by stripping out excess whitespace or the like.  This filter is not meant for a theme or plugin adding styles to the front-end of the site — for that, consider enqueueing your stylesheet normally and adding any dynamic bits via wp_add_inline_style() — this way it will also handle if a child theme or plugin wants to dequeue the parent stylesheet.

Jetpack has historically provided LESS and Sass (SCSS) preprocessing for our Custom CSS module.  We’re extending the Core implementation via two filters in the WP_Customize_Custom_CSS_Setting class by storing the pre-compiled code in $post->post_content_filtered — so it is versioned correctly, but if the user disables Jetpack, the compiled CSS will still be available in $post->post_content with no data loss for the user.

When implementing a pre-processor extension to the Custom CSS functionality in core you have to do some swapping between the underlying setting value and the value that gets displayed:

  1. Replace the post_content with the post_content_filtered as the initial setting value via the customize_value_custom_css filter.
  2. Add a wp_get_custom_css filter in the customizer preview (when the customize_preview_init action triggers) to compile the value into CSS just-in-time.
  3. Override the default JavaScript live-preview functionality to instead register a partial for the wp-custom-css style element so that whenever the custom CSS is modified it can be re-compiled on the server and rendered via selective refresh.
  4. When the Custom CSS setting is saved in the customizer, send the saved pre-processed value to post_content_filtered and compile the value to store into post_content.

For a standalone example of building a pre-processor, see the Custom SCSS Demo plugin on GitHub.


The Core implementation also is including only very basic sanitization, to the point where it would be dangerous to allow users without unfiltered_html to edit CSS.  If your plugin is adding further sanitization to the saved CSS, you can broaden the user base by remapping the edit_css capability (which Core defaults to unfiltered_html) like so:

add_filter( 'map_meta_cap', 'mycss_map_meta_cap', 20, 2 );
function mycss_map_meta_cap( $caps, $cap ) {
  if ( 'edit_css' === $cap ) {
    $caps = array( 'edit_theme_options' );
  return $caps;

Migrating an Existing option to Core CSS

Does your plugin or theme have a custom CSS option stored as an option or a theme_mod? Consider migrating content from your custom setting to the core functionality and hiding your custom UI. Here’s a general migration script, which can be located where you see fit in the context of your original code:

if ( function_exists( 'wp_update_custom_css_post' ) ) {
	// Migrate any existing theme CSS to the core option added in WordPress 4.7.
	$css = get_theme_mod( 'custom_theme_css' );
	if ( $css ) {
		$core_css = wp_get_custom_css(); // Preserve any CSS already added to the core option.
		$return = wp_update_custom_css_post( $core_css . $css );
		if ( ! is_wp_error( $return ) ) {
			// Remove the old theme_mod, so that the CSS is stored in only one place moving forward.
			remove_theme_mod( 'custom_theme_css' );
} else {
	// Back-compat for WordPress < 4.7.

I hope some of this has been useful to folks interested in diving deeper into modifying the Core Custom CSS editor.  It’s still somewhat early days for the feature, so please reach out in #core-customize on Slack with any unexpected use cases or concerns!

#4-7, #css, #customize, #dev-notes

Feature Proposal: Better theme customizations via custom CSS with live previews

When people ask “why WordPress?”, some of the most common answers center around flexibility for users of all kinds, whether they’re building their sites primarily through code or UI. Let’s take the story of a user who does a little of both – we’ll call her Becky.

Becky is a pretty savvy user. She knows that you’re supposed to make child themes instead of hacking on a theme directly, because updates can wipe out your changes. She found that out the hard way when she first started using WordPress – she hardly knew what CSS or PHP were, but she knew there was a theme editor in the admin and that she could make tweaks to colors or remove the author byline pretty easily without having to figure out this FTP stuff. Later on, most colors could be changed with the customizer so having a child theme just to remove an author byline seemed like overkill, but it was certainly better than having it reappear every time her site updated, especially with auto updates turned on.

After a couple years with the same theme on her personal site, Becky felt it was time to change things up. She was pleasantly surprised to find some new features that made getting a theme set up a lot easier, especially when live previewing them. Still, though, that pesky author byline remained, and since her last child theme copied a template to get rid of the byline, she would have to set up a whole new one to do it again. Then Becky found an “Edit CSS” option and realized she could hide things using CSS without having to go through the entire child theme process. Now, it turns out that those CSS tweaks didn’t come with live previewing, and that functionality was provided by a certain plugin, but Becky got what she needed to get done a lot faster than she would have otherwise, and ended up with the site she wanted.

This isn’t one specific story, but it is a combination of user stories many have heard, witnessed, or even personally experienced. You could replace Becky with @helen and it would be 100% accurate. The theme editor is a dangerous but useful entry point to more deeply customizing your site – rather than outright removing it and cutting off that introduction not just to WordPress code but to the concept of web development at large, why not provide a far safer and more user-friendly alternative? This post will explain why custom CSS with live previewing is valuable for WordPress and propose an implementation for inclusion in 4.7.

Proposed solution: Custom CSS with live preview

When bridging the gap between advanced user and beginning developer, desired changes are typically visual tweaks, such as changing a font size or hiding something, that are theme-specific. These sorts of changes should not require that users take risks editing live files that might white screen their sites or jump immediately into developer-facing tasks such as using FTP. Therefore, the scope of this feature has been defined as a custom CSS editor that leverages the customizer for a user-friendly live preview experience. This live preview allows for users to try various tweaks to a theme before saving and setting their changes live.

There are hundreds of thousands (if not millions) of users making use of custom CSS plugins or other themes/plugins that have custom CSS capabilities, and the frequent suggestion of CSS fixes in support forums justify a core need for this functionality. When plugins and themes interact in unexpected ways, CSS snippets are often an efficient solution to fixing the particular problem on particular sites.

The CSS editor takes inspiration from the many plugins offering similar solutions, but with an updated approach that offers instant live previewing in the customizer. The proposal for 4.7 looks like this:


Notably, previewing CSS in the customizer allows the site to be navigated and previewed on different sized devices by leveraging existing core features, allowing users to visualize the impact of their changes across their site. Error messages are shown for common syntax mistakes to help users ensure that their CSS is formatted properly before saving.

In future releases, the interface can be iterated on to further improve usability. The long-term design vision provides functionality such as revisions, syntax highlighting, and in-preview selector helpers, and can be implemented iteratively over time (click through for the full version):


CSS would be stored in a custom post type (without admin UI), with a post stored for each theme. The editor would be used to supplement and override theme styles rather than editing them directly, as users have long been advised that directly editing files may lead to lost changes during updates. Instead, custom CSS safely stays available through updating and switching themes, starting fresh for each new theme. Projects such as customize changesets (#30937) and revisions for customizer settings (#31089) would bring future enhancements to this feature and further leverage the opportunities that come with storing the data in post objects.

This is proposed as core functionality rather than remaining as plugin territory because it is designed as the first step toward a next generation of the existing theme editor in core, with a more refined feature set and safer, more user-oriented focus. The theme editor is not proposed to be removed at this time, though with the introduction of this feature it likely makes sense to introduce more friction before accessing the editor (#31779).


To improve the user experience further, it is critical that a link to documentation and resources for learning CSS be included with useful help text. This could initially be the “CSS” codex page but would ideally live on a user or developer handbook of some sort eventually (perhaps the theme developer handbook?). This help text must be much more succinct than the help tab on the existing theme editor, conveying what CSS is, where to learn about specific rules, and explaining that it’s specific to each theme in only a few lines.

Help is needed to create a resource for using custom CSS in WordPress, and locate it on WordPress.org. There are some related resources on make/training and WordPress.com has a good introductory page that they may be willing to contribute. Translated versions will eventually be needed as well. If anyone is interested in improving this aspect of the feature, which will presumably live on WordPress.org, please comment on this post.

Security, Capabilities, and Multisite

While the proposal includes basic validation, it is not possible to fully sanitize CSS. For this reason, a new meta capability will be introduced for managing css, unfiltered_css. By default, this is mapped to the unfiltered_html capability.

Site administrators on multisite networks do not have the unfiltered_html capability by default. A plugin that remaps unfiltered_css to a different capability can be created to provide this access on multisite, where custom CSS is especially useful given the need to restrict the number of themes and child themes in the network. This is an area of potential evolution over time.

Related Customize API Improvements

There are a couple of customizer API improvements introduced as part of the implementation of custom CSS in the customizer. A new “Code Editor” customizer control (WP_Customize_Code_Editor_Control) is used for the CSS editor and can also be utilized in plugins and elsewhere in the future. It currently handles line numbers and basic code styling, and will eventually add enhancements such as syntax highlighting.

Additionally, the WP_Customize_Section class has a new “description_hidden” parameter, which locates the section description in the section header behind the help icon toggle (“?”), functioning in the same manner as the customizer panel descriptions.


@johnregan3 is leading development of this project, based on initial work by myself (@celloexpressions). @folletto is leading design efforts, with a focus on the long-term growth of the feature for maximum usability.

The implementation takes inspiration from many of the numerous plugins and services that implement custom CSS, specifically including:

  • Simple Custom CSS (@johnregan3)
  • Modular Custom CSS (@celloexpressions)
  • WordPress.com Custom CSS in the design upgrade (Automattic)
  • Jetpack (Automattic)

Testing, Feedback, and Next Steps

Your help is needed in giving feedback on this proposal and testing the feature! To test, please apply the patch either via Trac or the PR (helpful reminder: grunt patch handles both) and try some custom CSS in the customizer using various themes.

Pending approval of this proposal, the next steps will be to finalize and commit the patch on #35395. Code review is ongoing in the GitHub PR linked on the ticket. Feedback on the feature in general and the specific implementation is encouraged via the comments on this post, with any more technical implementation discussion happening on the Trac ticket or GitHub PR.

#4-7, #css, #customize, #proposal, #themes

Updates to the default admin color scheme

Over on Make/Design, @hugobaeta has posted about some subtle updates to the blues and grays of the default admin color scheme. Work on updating the admin has been completed in #31234. For those who are using those colors in their development, particularly any large areas of colors such as backgrounds, you may want to take a moment to update those values. There’s a handy guide to the changes on the post.

While we haven’t yet settled on a sensible and semantic way to provide helpers or utilities for these kinds of CSS changes, thoughts and eyes are welcome on #26691 for that.

#4-2, #bikeshed, #css, #dev-notes

Core CSS: A potential roadmap to sanity

At the community summit, we discussed a core CSS roadmap, initially a discussion about preprocessors in regard to their role in WordPress, both in the admin and in bundled themes. Recently, there has been significant discussion about the initial use of a preprocessor in the development of Twenty Fifteen that was not included when it landed in core. We discussed what role preprocessors may play with our default theme development and core WordPress for the long term.

In this post, you will find some history, some observations, and an outline of where we can go next to bring some sanity to our admin CSS as well as move into the future.

Continue reading

#community-summit, #css, #roadmaps, #ui

Calling all CSS Gurus well everybody that…

Calling all CSS “Gurus”, well everybody that is interested in CSS to voice their opinions about The big CSS overhaul in 3.3.

#3-3, #css

Dashboard CSS

Dashboard CSS