WordPress: Add Controls to the Customizer Preview Window

If you’re a WordPress theme developer you are probably familiar with the famous/infamous Customizer. Some developers leverage it and some do not. I’m a huge fan of the customizer. I always use the API when I am creating themes. My clients are usually in awe because they can see changes in real time without affecting the client-side view until they are ready to save and publish their changes.

The Customizer isn’t perfect

As stated previously, I love the customizer. If you’re a developer who doesn’t leverage the power of the customizer and instead insists on creating these settings pages that resemble the dashboard of a 747, then all I have to say is, “What are you doin’?”

One shortcoming of the customizer is its control pane/window. It’s not very ergonomic. Too narrow. Not enough real estate for more complex controls.  Depending on the complexity of your theme, adding the customizer control pane will subtract from the user experience.

Add Controls to the Customizer Preview Window

I recently decided to rewrite my Ingleside theme. After playing with the custom customizer controls for a while, I realized that the UX had some room for improvement.



But what if I can remove a level/click or 2 from accessing the color controls? What if I can put the control on the preview window itself?

For the sake of this tutorial, I added a color picker under the top bar:

This tutorial won’t cover how to add a color picker to the preview window. Instead we will focus on the is_customize_preview function. This function returns true when the site is in customizer mode. Next, we have to make sure we pass the value of the color selection back to the desired customizer control. Keep in mind that the preview window is opened in a frame from the parent customizer control window. In order to access the customizer’s Javascript API, we have to traverse from the preview window to the customizer parent. In this instance, the control I need to access to change the color of the top bar is topbar_background_color. The following example can be placed in either the functions.php or your custom theme-customize.js. Please refer to the Customizer API documentation for more details. Here we call upon the window object to access the customizer controls:

As a bonus, if you want to open a particular control panel from the preview window you can use the focus method.

If you have any questions, suggestions or complaints, leave a comment below!