I'm trying to create multiple value customizer control like:

  • typography - Color, font-family, Size, etc ....

I could create a control and initialize each control class in the constructor, but how can properly group it to one container and label it for example: Typography.

Something like this ( not talking about any CSS ):

enter image description here


  • 1
    A "control with multiple fields" seems incorrect for me. You may want to take a look into customizer sections (UI containers for controls) and customizer panels (UI containers for sections). See more in Customizer Objects.
    – cybmeta
    Aug 2, 2016 at 7:29

1 Answer 1


There are 2 ways to handle customizer control templates: 1. Using a PHP template 2. Using a JS template.

The screenshot you posted above is from the Kirki plugin. Kirki uses JS templates, so you can see how that's done here. For the sake of simplicity I would advise you to look at this control instead since the typography control is over-complicated (gets google fonts and modifies the select dropdowns depending on the other options): https://github.com/aristath/kirki/blob/2.3.5/includes/controls/class-kirki-controls-multicolor-control.php

You basically have to create the markup for al those input fields separately... or -as in the case of the multicolor control above - use a loop.

and then comes the JS part of the WordPress Customizer API. If you take a look at the https://github.com/aristath/kirki/blob/2.3.5/assets/js/controls/multicolor.js file that is responsible for the multicolor control, you'll notice that on line 8 it gets the control's choices (which is where I've chosen to put the arguments that I need), and then on lines 47-59 it runs a loop for those choices and precesses them accordingly.

Granted, that code is a bit more complicated than needed but that's just because it's dealing with colorpickers. You can simplify it a lot if you're working with textfields, radios and/or select fields for example.

The basic steps you should follow in order to build a control like this are:

  • Build a custom control and use underscore.js templates for it. That means using the content_template() method to add your template.
  • Expose your data to the Customizer's JS API: Inside your control you will have to use the to_json() method. For an example in the Kirki plugin look here: https://github.com/aristath/kirki/blob/2.3.5/includes/class-kirki-customize-control.php#L124-L150
  • Write a custom JS script for your control and enqueue it using the customize_controls_enqueue_scripts action.
  • Inside your custom JS script for your control, get the data that you exposed from your control using the to_json() method, and then you can use that data to do whatever you want. If you want to save multiple values for your control, you'll have to save them as a JS Object, getting the value of each of your input fields and saving its value as an item in the object, using the field's ID or whatever you choose to use as the key in the object.
  • Thanks, I thought there is a cleaner way to output the controls templates. so if I want to add the built in color or media control I have to copy the code of the template and enque like here:developer.wordpress.org/reference/classes/…
    – Yehuda
    Aug 2, 2016 at 19:38
  • Pretty much yes.
    – Aristeides
    Aug 3, 2016 at 9:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.