Build Customizer Controls Faster

If you are a WordPress theme developer, you're likely to spend hours making your theme customisable via the WordPress customizer. Adding settings, connecting them to controls, trying not to lose the overview. Kirki is a simple and free framework, that allows you to quickly add more than 30 advanced controls with a simple syntax. All the controls are beautifully designed and specifically optimised for the WordPress customizer.

There are several very good reasons to consider Kirki as your go-to framework for quickly building and adding customizer settings. It has a simple syntax, so it can be learned by anyone. Kirki has already been in development since 2014 and it's still actively improved and maintained.

1. Plenty of controls

Kirki really offers a plethora of options and controls. All those can be used without any additional registering. So it's likely you'll never need to register and build your own controls, as Kirki already offers a lot of advanced controls.

Basic (core) controls include checkboxes (and several beautiful versions of the default checkbox), color pickers, images, text, textarea, radio, number, url and more.

Several advanced controls include the background control, typography control, dimensions, dropdown pages, multicolor, sorting fields, color palettes, the TinyMCE editor and of course a repeater. You can have a look at all the controls here.

2. Very easy to learn

Kirki has a very simple syntax. You just specify one array with the configuration for every field (see below about the term 'field'). Adding a field looks like this:

Kirki::add_field( 'theme_config_id', [
    'type'        => 'color',
    'settings'    => 'color_setting_hex',
    'label'       => __( 'Color Control (hex-only)', 'kirki' ),
    'description' => esc_html__( 'This is a color control - without alpha channel.', 'kirki' ),
    'default'     => '#0088CC',
    'section'     => 'section_id',
    'priority'    => 80,
] );

This is an example of how to add a color field. Let's have a short look at every parameter to get an idea of how Kirki works.

Type: specify the type of control you want. It takes values like color, text, textarea, background and typography.
Setting: this is the name under which the value is saved in the database. It is also the name you use to retrieve the value with get_theme_mod(). This line completely replaces the $wp_customize->add_setting().
Label and description: those parameters speak for themselves. Note that both are optional, so omitting (one of) them is not a problem.
Default: also a self-explaining one. Enter the default value. Can be both a string or an array (typography control or other controls that take on multiple values). Can even be a multidimensional array in the specific case of a repeater.
Section and priority: the section where the field should appear and the priority. The higher the priority, the higher the position.

As you can see, the syntax of Kirki is really easy. After adding a few controls, you'll certainly get the hang of it.

Controls vs. settings

If you do already know the default WordPress customizer syntax, you're perhaps a bit confused when talking about controls and settings. In the default customizer syntax, a setting is the value of a control that is stored under a specific name in the database. And a control is the thing which controls that value. For example: a color picker. The hex-code is the setting and the color picker itself is the control.

Kirki combines those two concepts into one that's called a field. I'll usually just talk about a field or a control. The term 'setting' is a bit illogical in my point of view, because it's logical that every control also has a setting.

3. Front-end CSS output

Another big advantage is the automatic CSS-output. For every field, you can add an output parameter to the field's configuration array. The output parameter is an array, that contains in its most basic form

the CSS-selector to output; and
the CSS-property (color, background-color, padding, etc.).

It looks like this:

'output' => [
  [
    'element' => '#header > .header-logo.mobile',
    'property' => 'background-color',
  ],
],

The CSS is outputted in a <style>-tag in the <head>. The above example will output

#header > .header-logo.mobile { background-color: #0088CC; }

The code is always minified. It also works for booleans and numbers:

[
  'element' => '',
  'property' => '',
  'units' => 'px',
],

4. Make it as advanced as you want

The above example was still a relatively easy example. There are many more options and things you can add to tweak Kirki to work even better with your theme. Those options are usually not needed by default, but as you learn more about Kirki, you're likely to need some more advanced options too.

Unfortunately, most of those options aren't documented. For example, when I learned Kirki, I had a hard time figuring out how media queries work.

For if you're curious, turns out that it's really easy:

'output' => [
  [
    'media_query' =>'@media (max-width: 799px)',
    'element' => '#header > .header-logo.mobile',
    'property' => 'background-color',
  ],
  [
    'media_query' => '@media (min-width: 800px)',
    'element' => '#header > .header-logo.desktop',
    'property' => 'background-color',
  ],
],

Besides media queries, there are a lot more advanced tricks. I'll all describe them in future articles, because currently it is very difficult to find some, if any, documentation about it. Tip: the most info can be found in the Github issues, so it's worth doing a search there for some code examples. You can of course also add an issue, there's a really active community with a lot of friendly people.

5. Automatic postMessage

Kirki also takes care of postMessage Javascript. Developers used this to real-time update the preview when a control changed values. With the default WordPress syntax, you had to write specific Javascript for updating the CSS of the preview. Kirki can now take care of this task. With this, you can make the customizer user experience a whole lot smoother, with a minimal amount of extra work. It's just a simple parameter for every field.

'transport'   => 'auto',

Disadvantage is that you'll need to add this to every field you register. But in comparison to writing Javascript yourself, this is a huge thing timesaver.

Of course Kirki also has support for custom postMessage, so if you're ever in need of a custom Javascript function, you can also use a Kirki field for that.

6. Active development

I already mentioned that Kirki is being actively developed and that is has a huge fanbase. If you're stuck, there's almost always somebody who's wanting to help you. Just add a Github issue and describe your problem. My problems have always been solved by some active community member or a Kirki developer.

7. Kirki speeds up the customizer

Almost every developer knows that frameworks reduce the speed of something. But in some cases, when frameworks are doing clever things, they can speed things up.

This is also with Kirki. When the customizer is loaded, WordPress loads everything already, even if sections and controls are not yet visible. Especially with themes that feature a lot of options, this can take a while. Kirki postpones loading, and only loads things just before they're needed. This speeds up the customizer.

8. Can be used together with the default WP customizer syntax

The nice thing is that you can combine both the default WordPress syntax and the Kirki syntax. This means that you can just register panels, sections, controls and settings in the classic way, in combination with Kirki.

So if you have created your own customizer control or something else you want to keep using, that's no problem at all.

More Kirki stuff?

Using Kirki for developing Customizer-compatible WordPress themes is a huge timesaver for every developer. Thanks to its easy-to-learn syntax and the advanced features, almost everything you'll need to do with the customizer can be achieved with Kirki.

In the future, I plan to write more articles featuring advanced Kirki tricks and documenting advanced parameters and functions. There's currently no place in the internet that has a complete documentation of everything about Kirki and especially about the more advanced things.

Published by Ralph J. Smit on 12 November 2020 in Kirki . Last updated on 22 April 2022 .