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.

* Display upgrade notice on customizer page
function prefix_upsell_notice() {
// Enqueue the script
get_template_directory_uri() . '/js/upsell.js',
array(), '1.0.0',
// Localize the script
'prefixURL' => esc_url( '' ),
'prefixLabel' => __( 'Theme Upsell Link', 'textdomain' ),
add_action( 'customize_controls_enqueue_scripts', 'prefix_upsell_notice' );
view raw upsell-enqueue hosted with ❤ by GitHub


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.

* Upsell notice for theme
( function( $ ) {
// Add Upgrade Message
if ('undefined' !== typeof prefixL10n) {
upsell = $('<a class="prefix-upsell-link"></a>')
.attr('href', prefixL10n.prefixURL)
.attr('target', '_blank')
'display' : 'inline-block',
'background-color' : '#2EA2CC',
'color' : '#fff',
'text-transform' : 'uppercase',
'margin-top' : '6px',
'padding' : '3px 6px',
'font-size': '9px',
'letter-spacing': '1px',
'line-height': '1.5',
'clear' : 'both'
setTimeout(function () {
$('#accordion-section-themes h3').append(upsell);
}, 200);
// Remove accordion click event
$('.prefix-upsell-link').on('click', function(e) {
} )( jQuery );
view raw upsell-js hosted with ❤ by GitHub

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'm a WordPress developer based in Austin, Texas. I run a little theme shop called DevPress and work for a startup called Cratejoy. Find me on twitter @devinsays.

3 Responses

Leave a Reply