Details on the new theme settings (customizer) guideline

During yesterday’s team meeting, we made what we knew would be a controversial decision about theme settings. This post will go into more details about this decision and how we plan to move forward.

The new guideline

In a nutshell: Themes are now required to utilize the CustomizerCustomizer 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. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. if the theme has custom theme settings. This means no custom settings screens.

Generally, new guidelines go into effect immediately. This is to avoid confusion over which guidelines are in effect and which are not.

However, that’s not the case this time around because we feel that this is a unique situation. Only new themes (submitted since the announcement yesterday) fall under this guideline right now. Then, 6 months from yesterday, all existing themes submitted to the repository fall under this guideline. So, mark your calendars for October 21, 2015.

To be clear, we will not be suspending existing themes or anything like that. What will happen is that when you next make a theme update (after the 6-month cutoff), your theme will need to follow the guideline.

The new guideline is also reflected in the handbook required section.

Why now?

First, I want to say that the team did not take this decision lightly nor did we make it quickly. In fact, this has been an ongoing discussion for nearly 3 years (since the customizer was first introduced in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.). Many of us had originally hoped that we could take a more organic approach to this and allow theme authors to naturally make the switch on their own given enough time.

The decision was ultimately made on two fronts:

  • Having a consistent experience for users (most important thing).
  • Standardizing the theme review process.

It is our team’s belief that having a standard and consistent user experience will benefit all involved in the long term. Core has also moved most of it’s built-in theme-related settings completely to the customizer as well.

While users were our first concern, the review process was also a concern. I won’t pretend it didn’t play into our decision. Honestly, reviewing themes with non-Customizer settings screens has slowed down the process. Each time a new theme with its own options panel comes in, the reviewer must learn an entirely new settings system. Then, a TRT admin must learn it. We must understand the code to review it because theme settings are one of the biggest areas for possible security issues. Another issue here is that many theme authors simply didn’t understand the code themselves (loads of copy/paste), which makes it next to impossible to have a discussion on specific options-related items.

Ultimately, the team thinks this is the best way forward.


I’ll try to cover a few of the questions we’ve been fielding since yesterday.

Can I use XYZ framework/library/script?

That depends on whether the framework falls under the theme review guidelines.

I’d like to see us get away from frameworks. This is not because I don’t like them (I actually like many). It’s because I believe it’s important to understand the underlying code, which is an important part of the problem that we’ve been running into. Sometimes, frameworks are utilized when they’re not actually needed.

This also means we haven’t been doing our job on the education front. We should make a better effort at teaching theme authors about using the customizer.

Can I use XYZ pluginPlugin 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 Plugin Directory or can be cost-based plugin from a third-party for settings via TGMPA (TGM Plugin Activation)?

You can certainly recommend any plugins hosted on WPORG that your theme integrates with via the TGMPA script. You could integrate with these plugins just like you would with bbPressbbPress Free, open source software built on top of WordPress for easily creating forums on sites., BuddyPress, WooCommerce, etc. However, keep in mind that all themes must function correctly without any plugins installed.

We’d love to have everyone on the customizer, but if you just can’t do that, there’s your loophole.

Isn’t this limiting developers?

Yes, standards are always limiting in some ways. Our entire set of guidelines are limiting specific items. TRT’s goal has always been to require the use of core functionality if that functionality exists in core. The Customizer is core’s answer to theme settings.

This is so much larger than us simply limiting developers for the sake of utilizing core methods. The primary focus is the consistent user experience.

The customizer doesn’t handle the XYZ field. What should I do?

You should see about extending the customizer. It’s an OOP approach to theme setting panels that allows all kinds of cool things to be done. I’ve personally built several different custom controls by simply extending the WP_Customize_Control class.

I’m also volunteering my coding services for $free if anyone needs help building a custom control for the customizer. I can’t guarantee that I can build everything, but I’m sure there are others who are willing to help. Feel free to post requests in the comments below.

It’s not going to be easy at first, but we think this will benefit the entire theme development community in the long run.

But, the customizer sucks!

I’m sorry you feel that way. This is an open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project in which all are welcome to participate. If you really have legitimate issues with the customizer, please get involved with its development in core. That’s the best way to make changes happen.

Where can I learn more about the customizer?

Here’s a few tutorials and docs to get you started. I hope that we, as a team, can bring you more educational resources in the coming months.

Questions? Comments?

We understand there’s going to be some pushback about this decision. You are more than welcome to voice your concerns. Please keep in mind that this should be a positive experience.

Our ultimate goal is to have awesome themes in the repository. Let’s work on ways to make that happen rather than arguing about whether this was the right decision.