Practical WordPress Development

The WordPress Theme Customizer: Adding a New Setting To An Existing Section

Since the release of the WordPress Theme Customizer, my team and I have been more and more interested in using it as a way for users to make changes to the appearance of their theme without the use of the dashboard.

As powerful as the dashboard is, the “Appearance” section creates a disconnect between what the user toggles (or selects, or inputs, etc), and what they see on the front end.

The Theme Customizer mitigates that issue.

The thing is, there are a few nuances that come with implementing it in your theme. Though I’m not trying to cover everything here, the point of this post is show how you can introduce a new setting into an existing section.

The WordPress Theme Customizer: New Setting, Old Section

For those of you who aren’t familiar, the WordPress Theme Customizer is an API that was released in WordPress 3.4. Several of the more recent themes that ship with WordPress include it:

WordPress Theme Customizer

In short, it’s a way for you to make changes to the appearance of your theme on the fly. On top of that, it’s completely customizable such that whenever you introduce a new setting into your existing theme, you can add new sections, settings, and so on to the theme customizer.

But that’s another post.

Adding a New Setting To An Existing Section

Here, I’m more concerned with documentation how to add a new setting to an existing section as well as sharing how I organize my files for working with the theme customizer.

It’s not so much that I think my way is right anymore than someone else’s way, but I do prefer to keep my files as compartmentalized as possible so this should share that, and it should show how to introduce a new setting into an existing section.

The File Structure

As I mentioned, there are a number of ways that you implement the WordPress Theme Customizer, but there has been my preferred method for some time now:

  • Create an `inc` directory in the root of the theme
  • Create a `theme-customizer.php` file in the `inc` directory
  • Call an `include_once` to the `theme-customizer.php` file in `functions.php`
  • Create a `js` directory in the root of the theme
  • Create a `theme-customizer.js` file in the `js` directory

This should be clear enough.

WordPress Theme Customizer File Organization

Though I use CodeKit to manage my JavaScript, CSS, images, and other assets, this should provide you with enough information for how I organize my theme files.

Implementing The New Setting

So anyway, once you’ve done all of that, it’s really easy to begin implementing the theme customizer.

First, you need to register your JavaScript file with the `customize_preview_init` action:

function my_customizer_live_preview() {

		  get_template_directory_uri() . '/js/theme-customizer.min.js',
		  array( 'jquery','customize-preview' ),

add_action( 'customize_preview_init', 'my_customizer_live_preview' );

Then you need to define a function that will be added to the theme’s theme customizer by using the `customize_register` function.

In this case, I’m looking to introduce a new option specifically for changing the link color and I am looking to add it to the existing Colors section in the theme customizer.

function my_theme_register_theme_customizer( $wp_customize ) {

	$wp_customize->add_setting( 'link_color',
			'default'     => '#000000',
			'transport'   => 'postMessage',

		new WP_Customize_Color_Control(
				'label'        => __( 'Link Color', 'my_theme' ),
				'section'    => 'colors',
				'settings'   => 'link_color'

	$wp_customize->get_setting( 'link_color' )->transport       = 'postMessage';

add_action( 'customize_register', 'my_theme_register_theme_customizer' );

Above, the key is that the `add_setting` must come before the `add_control` call.

At this point, this should introduce a new setting in your theme customizer, though it won’t actually be functional since there isn’t any JavaScript, yet.

WordPress Theme Customizer Link Color

Can’t show too much of this theme yet. :)

Next, you need to implement the necessary JavaScript in the `theme-customizer.js` file that was discussed earlier in the post.

To do this, you need to understand two things:

  • Implementing the WordPress Theme Customizer exposes a JavaScript object that offers a function that allows you to specify the setting that you’re going to modify.
  • You need to know the selector for which you’re going to modify. To keep it simple, I’m modifying all anchor elements.
(function( $ ){
	"use strict";

	// The Background Color of the Header
	wp.customizer( 'link_color', function ( value ) {
		value.bind( function( newVal ) ) {
			$( 'a' ).css( 'color', newVal );

}( jQuery ));

Finally, assuming that you’ve got it all wired up in `functions.php`, the implementation should be good to go within the theme customizer. Again, this is specifically for adding a new setting to an existing section.

Working with custom options isn’t bad, but it’s a whole other post.


  1. Richard Buff

    Great article, but can I ask an unrelated question it made me think of? In the theme folder, sometimes I see people use “lib” to include theme assets (example: and other times I see them use “inc”, as you’ve done here. Is there a reason for one vs the other?

    • Tom McFarlin

      Different people may have different takes on this, but this is how I’ve always implemented it in my work:

      • `lib` is normally for third-party assets and tools that are not written by the developer or the development team
      • `inc` is for assets that are developed in-house or by the main developer, but not meant to clutter up the core `functions.php` or whatever file(s)

      That’s how I’ve always used it. Perhaps I’ll do a longer blog post on this soon.

  2. Richie KS

    ah..finally, i’ve been looking for a tutorials on this. thx tom
    btw is it possible to allow customize panel for none loggedin user? maybe exclude the save/publish button.

    • Tom McFarlin

      There’s almost always a way to get something working when it comes to programming, but this particular feature is one meant for users who are logged in so that’s where I’ve gotta leave this tutorial :).

  3. Richard Buff

    Awesome thanks for the explanation Tom. A blog post on this sort of naming convention would be rad too.

  4. Aaron Rudd

    Thanks so much for this, it works great.
    I have one question…
    As I attempt to pull the color from the admin to the template, what does that piece of code look like?

    • Tom

      If the feature is implemented correctly in the customizer, then you’ll use the ID that you specified – say `acme_color` – and then retrieve it by calling `get_theme_mod( ‘acme_color’ );`.

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑