Custom Links in the Customizer


Adding custom links or markup to the theme customizer can be a bit difficult since everything is injected with javascript rather than the normal PHP toolkit. However, there are a number of use scenarios where this might be useful.

One common use case for theme authors might be to add a documentation link or an upsell link so users can find out about theme features.

The approach I like the best is one I first saw employed by the Theme Foundry with their theme “Make”. Their upsell link is prominent, but it doesn’t detract too much from the theme customization experience or take up too much space in the limited UI.


This tutorial takes a similar approach, but shows how to add a styled link to the “Active Theme” section.

Enqueue Scripts

To enqueue scripts specifically for the customizer, we’ll need to hook into the customize_controls_enqueue_scripts action.

We’re going to load one script “/js/upsell.js” and also output the link text in a way that will make it translatable (using the wp_localize_script) function.


This javascript creates the markup used for the link button, and appends it to the theme section in the customizer. Because the theme section might take an extra few cycles to load, there’s a short timeout before appending the markup.

You may notice that all the styles for the link are also added inline directly on the element. An alternate method, which might work better is to use the wp_add_inline_style inside the customize_controls_enqueue_scripts to add those styles inline at the head of the document.


I have some reservations about writing a tutorial like this because I’d hate to see the customizer ruined with custom markup that doesn’t match core styling, or even worse, huge upsell sections that make the customizer unusable.

As always, use good discretion, try to match core styling, and keep the end user in mind!

Update: Justin Tadlock also has a method for adding upsell links for themes. See on GitHub.

About Devin

I am a developer based in Austin, Texas. I run a little theme shop called DevPress and help manage a WooCommerce shop with Universal Yums. Find me on twitter @devinsays.

4 Responses

  1. jockebq

    I am trying this with WP 4.9 but I am not able to make it work. I use the Enqueue script PHP part directly in my themes functions.php without .
    Nothing shows up in Customizer.

    Any ideas?

    Thank you!

Leave a Reply