WordPress Theme Developer Handbook Updated with Comprehensive Guide to the Customizer API

on May 4, 2015
photo credit: Artist's Room - (license)
photo credit: Artist’s Room(license)

The Theme Review Team’s controversial decision to require the use of the Customizer API for building theme options unearthed a wave of criticism and concern about the capabilities of the customizer.

In response to more than 150 comments debating on the topic, Nick Halsey, who has worked extensively on the feature in WordPress core, stopped by to offer a few words in support of the Theme Review Team’s decision:

Many of the comments here are misinformed or unaware of both the full power of and the future importance of the Customizer. I’ve given an overview of my perspective on my blog, and while those views don’t directly represent the views of the WordPress project, I can say that most people working on the Customizer in core would agree with my points. Like it or not, the Customizer is here to stay, and ignoring that fact will eventually cause users to turn against you.

Halsey’s post calls for theme developers to re-examine their philosophies when it comes to building complex UI options and stop re-inventing the wheel. He believes the customizer has more creative potential than developers give it credit for.

Complaints about the amount of screen real estate available and the 300px default width show a lack of creativity and resistance for the sake of resistance to change. Start by removing all of the ads, external links, unnecessary branding, unnecessary options, and general clutter. Make your options self-explanatory – if you need a paragraph to describe what it does, it probably shouldn’t be a user-facing option. Do you still have so much UI that the experience is completely unusable? Try an outside-the-box solution, like utilizing the core media modal (header images and core media controls use it), a custom modal (theme details modal in core), or a slide-out panel (widgets in core and eventually menus in core as well).

Prior to the Theme Review Team’s decision, documentation on theme development with the Customizer API was sparse and claims about its wide range of capabilities were difficult to support.

Resistance from theme developers has WordPress.org contributors scrambling to produce better documentation for using the customizer in themes. Over the weekend, Halsey created a canonical developer tutorial on the Customizer API in the official theme developer handbook.


This official comprehensive guide includes the following sections and provides detailed examples for each:

Theme Review Team admin Justin Tadlock posted more details clarifying the new WordPress.org guideline and included a list of additional resources for learning more about the customizer.

Over the weekend, Samuel “Otto” Wood, who has written several customizer articles over the years, wrote a “What’s new with the Customizer” tutorial that explores some of its newer features in depth, including panels, active callbacks, and customizing the customizer.

With WordPress 4.3 blazing forward on customizer improvements, now is the time for theme developers to familiarize themselves with the available documentation and tutorials in order to be ready to take full advantage of WordPress’ core-supported method of providing live previews to users.

Source: WP Tavern

WordPress Theme Developer Handbook Updated with Comprehensive Guide to the Customizer API

Related Posts

Take a look at these posts