I’ve spent a lot of time recently in the WordPress Customizer for this theme and a client theme, and have found it slow to locate helpful references and tutorials. Part of that was not learning until recently that you can put a single word in quotation marks to keep Google from helpfully trying other word forms and synonyms to get you more results (“custom” and “customize” are far from interchangeable with “Customizer” in this context, so thank you SearchReSearch for the trick), but some of it was a lack of good material.

On with the show…
The fundamental source is the Customizer page in the WordPress Developer Handbook. What it covers it does well, but it is pretty cursory. In some ways I find the old Customizer information in the Codex easier to read.

Other General Tutorials and Examples

WPShout is a reliable source for entry-level tutorials that aren’t shallow, and you may find their Customizer introduction and overview helpful.

Tom McFarlin wrote a tutorial series for WPTuts+ that is well-explained. You can find an index for the WPTuts+ series on his blog.

The WPTuts+ series is a few years old, as is this Theme Foundation Customizer tutorial, which moves a little faster but is a little more comprehensive. However, the basic syntax is largely unchanged.

There’s a general introduction on Noupe that covers some of the same ground, but in a different way and with some different inclusions.

Tom McFarlin has suggestions on organizing your code for maintainability that will already be the case if you are working from Underscores.

Here are two WordPress themes on GitHub that use the Customizer and have authors who know a lot about the Customizer: Hybrid Core by Justin Tadlock; Oenology by Chip Bennett.

Adding Custom Controls

WordPress provides a number of control types: checkbox, radio button, select box, textarea, dropdown of pages, color picker, and media selector. You can add your own on top of these.

If you are adding controls, whether custom or built-in, the input needs sanitation; ThemeShaper has an article on validation and sanitation for the Customizer.

Otto has a good introduction to custom controls that is a little old but still relevant.

WPMU DEV has another intro, including the built-in controls, that might be good for a second explanation.

Justin Tadlock has a tutorial on a control that replaces radio buttons with images but still acts as a radio button control.

I found it easiest to understand custom controls via example. There are lots of collections of premade custom controls on GitHub that you can use and learn from, with a variety of authors: the WordPress Theme Review Team, Paul Underwood, and Frank Bültge for three (but see last week’s post for a caveat). Braad Martin has a control for a color picker with alpha. You can also see custom controls in action in the WP Customize Posts plugin by Weston Ruter.

Contextual Controls and Partial Preview Refresh

Contextual controls are those that appear and disappear based on what you’re previewing or what choices you’ve made in other controls. It and partial refresh are frequently covered in the same articles so I grouped them together. I discuss both in last week’s post, for one.

Otto talks about active_callback for contextual controls in a post about recent changes to the Customizer as of May, 2015.

In a Stack Exchange answer, Weston Ruter discusses the JavaScript alternative to active_callback.

WPShout covers partial refresh and active_callback in their follow-up to the general tutorial.

The Future: More JavaScript, Less PHP

Right now you can avoid JavaScript entirely provided you don’t mind the entire preview refreshing to update and you don’t want to hide and show controls dynamically. Since WordPress is great about back-compatibility, that probably will always be true. However, the future of the Customizer is in JavaScript. [Since the Customizer is pointless without JavaScript even my progressive-enhancement-obsessed soul can’t object.] Here are four links about using JavaScript for everything:

Weston Ruter in Make WordPress Core on how things work and where they’re going, October 2014.

Nick Halsey also in Make WordPress Core on rendering custom controls with JavaScript, in particular; November 2014.

Justin Tadlock has also written about rendering custom controls with JavaScript.

Finally, if you have a lot of options in the Customizer (the wisdom of that may be debatable) and they are injected with JavaScript, you may find your script is noticeably laggy. Here’s an article by Layers on speeding up the Customizer via delayed loading of controls.

I haven’t tried to implement a JavaScript-only Customizer in Amalgamation yet, but it’s on the list.