How do we solve the theme options problem?

Users love options, right? That’s the reason we add them as theme authors. While I think there’s a lot to be said about themes with no options that make sound design decisions, I won’t get too much into that right now. Rather, this post is about solving the major issue we’ve had for years as theme reviewers and theme authors trying to get their themes on the repository.

Up until a week ago, we allowed theme authors to create theme options in one of three ways — Theme 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., 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., or with custom options pages using the Theme Mods API. We’ve since narrowed that down to only allowing use of the Theme Customizer (strongly recommended) and Settings API. This was a pretty great move, but it doesn’t really solve 99% of the issues with theme options. Most everyone has already been using those things.

Realistically, the problem has come down to education. There are resources out there available for using these things. However, those tutorials are often written by programmers who aren’t great teachers or writers who are not so good at programming.

One of the things I’ve always hoped the TRT would become is more of an educational team. I firmly believe that if we didn’t have to spend so much time dealing with theme options, we could spend more time on educating in other areas of the dev/design.

I’m writing this post to open a dialogue for everyone on how best to approach this problem.


The issues I’m laying out here are based on my own personal observations and some things that I’ve heard from other reviewers. As an admin, I’m tasked with doing final reviews on themes before they go live. These issues are often missed by the first reviewers. This is not to lay blame on them. Frankly, it’s a tough job reviewing theme options, especially when no two theme options pages are even coded remotely the same.

Sanitizing, validating, escaping

By far, this is the number one set of problems we run into. What I’m seeing:

  • Themes don’t do any of these things.
  • Themes do one thing but not the other (e.g., sanitizing input but not escaping output).
  • Themes use the wrong functions (e.g., esc_attr() to escape a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL

Options saved by default

This has become less of a problem recently, but I still see it on occasion. Themes should be using sane defaults rather than saving default options to the database.

Frameworks, libraries, etc.

There are a number of theme options libraries available for theme authors. These are some awesome tools. However, what’s happening is that theme authors are using these things as a crutch and not learning how the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. WordPress APIs actually work.

This creates a problem because it can be hard to explain how to correct an issue if a theme author doesn’t have the basic foundation that they need to work with theme options. This effectively eliminates a great moment to educate theme authors because we’re not on the same page.

Fixing the issues

I’m writing this post because I believe this to be the biggest hangup with themes today. It’s the hardest part of the review process. It’s also one of the most critical because theme options means potential security issues.

I’d honestly love it if all themes would just use the customizer. That’d solve a ton of problems. However, it would be too limiting to theme authors who are doing some awesome stuff. I wouldn’t want to punish good devs by requiring the use of the customizer just so we can fix everyone else’s problems.

My initial proposal is that we build educational tools/tutorials for handling theme options. These need to be written more clearly than developer resources because many theme authors don’t come from a development background.

Another thing we should be doing is strongly pushing theme authors to utilize the theme customizer.

What are your thoughts? What do you think will benefit both theme reviewers and authors? How can we better educate people on these common issues?