WordPress Theme Review Team Sets New Guidelines for Custom CSS Boxes


Custom CSS boxes in themes are a common feature that allow users to easily add their own styles without having to edit any theme files. The inclusion of this feature in themes, as opposed to plugins, has long been a hotly contested issue among theme developers.

WordPress.org Theme Review team admin Justin Tadlock announced today that the team has agreed upon new guidelines for the inclusion of CSS boxes. He summarized the conclusions following the debate:

  • It’s preferred that theme authors leave this feature to plugins.
  • However, it is allowed if handled safely.
  • The edit_theme_options capability is required (like all theme options).
  • The wp_filter_nohtml_kses(), wp_strip_all_tags(), or equivalent function must be used to sanitize the data before it’s saved into the database.

The main issue here is sanitizing the CSS to make sure it’s safe to store in the database. The guidelines do not cover validating the CSS, as that is less of a safety concern.

While adding custom CSS boxes still falls within theme territory, it is best to consider relegating this feature to a plugin in order to keep your theme safe and lean. If you still wish to offer this feature in your theme, Tadlock posted sample code that will provide a good starting place for adding a custom CSS box to WordPress’ native customizer.

Commercial theme authors who want to keep pace with WordPress.org theme review requirements will want to review the updated guidelines. The theme review team recommends using a plugin, such as Jetpack’s custom CSS module, as a safe alternative to allowing the theme to save custom CSS to the database.

Would you like to write for WP Tavern? We are always accepting guest posts from the community and are looking for new contributors. Get in touch with us and let's discuss your ideas.


  1. Good idea, about time! I would hope but not really expect that the idea of custom CSS within a theme’s option page is also a bad idea because it creates yet more stylesheets that kill performance. Mobile page load speed, anyone?


    1. Such a feature would actually be faster than loading an extra stylesheet, provided the theme isn’t doing anything weird. Neither method is likely to be the bottleneck in performance.


  2. Terrible idea. CSS changes are generally theme specific and refer to theme specific display. They should be part of the theme and not added extra bloat of yet another plugin. Yes the data should be properly sanitised BUT don’t make us add yet another plugin for something so simple as this.


    1. It’s true that many CSS changes are theme specific. They’re also often specific to the site, regardless of the theme. I’ve been doing this long enough to see the various use cases. It just depends on what the user needs. Fortunately, plugins can and do handle both scenarios. Themes cannot.

      From a user standpoint this may seem “simple”, but it’s really not. Otherwise, we would’ve never had multiple discussions on it. There’s a lot of complexity to doing this and doing it right. What the new guidelines propose is to merely do it safely. We’re not forcing theme authors to do it right.

      Also, there is absolutely no difference in “bloat” between a theme doing it and a plugin doing it.

      I won’t even dive into the implications that such a feature would have on some multisite installs. The theme probably wouldn’t be allowed.

      The best and recommended method is to simply edit the style.css file (preferably via a child theme). Anyone comfortable enough to add code to their site should be comfortable enough to edit this file.


      1. I was going to mention using a child theme but Justin beat me to it. There’s also the Jetpack plugin with Custom CSS enabled, but I know everyone is divided on that subject already.


  3. A good idea to ensure that the CSS is sanitised however a bad idea to insist on yet another plugin to do something that is theme related. Plugins are to add functionality. CSS is about display and this is what is handled by a theme and so CSS changes are theme specific and should be part of the theme and not add the additional bloat of yet another unnecessary plugin.


  4. For those that don’t use Jetpack I recc Simple Custom CSS. We recc to our users and has always worked great.


  5. I can see why Jetpack has a custom CSS feature. Users of wordpress.com cannot create child themes. But that limitation does not exist on self-hosted sites.

    I understand there are different situations but, in general, the way I see it is that if someone is savvy enough to write custom CSS then they are savvy enough to create a basic child theme.

    If you have X amount of time available, why not use it to create a guide and example child theme rather than to develop an arguably unnecessary theme feature? It’s better to train people than to encouraging shortcuts.


Comments are closed.