How to add icons to customizer panels and sections

The WordPress customizer is a great way to add theme options to a WordPress theme. The controls in the customizer are added in sections or panels. This allows you to structure your theme options. But when you have several extra panels or sections registered, things can start to become a bit unclear. In this tutorial you'll learn how to easily add icons to panels in the WordPress customizer, which greatly improves the look and feel of the customizer.

One of the easiest ways to add icons to WordPress customizer panels and sections is by using the Kirki Customizer Framework.

Several panels in the WordPress customizer.

With icons added to panels and sections.

Registering panels with Kirki

Registering panels and sections is very easy to do with Kirki. We'll make use of the add_panel() and add_section() function.

Registering a panel with Kirki

Kirki::add_panel( 'panel_id', [
    'priority'    => 1,
    'title'       => esc_html__( 'Panel name', 'text-domain' ),
] );

Registering a section with Kirki

Kirki::add_section( 'section_id', [
    'priority'    => 1,
    'title'       => esc_html__( 'Section name', 'text-domain' ),
] );

Both the add_panel() and add_section() take the same parameters. The first parameter is the section_id or panel_id. The second parameter is an array with additional information about the priority, the title and perhaps a description.

Adding icons to WordPress customizer panels and sections

How do we add icons to this? It turns out that it's only a simple key and value combination in the array.

Kirki::add_panel( 'panel_id', [
    'priority'    => 1,
    'title'       => esc_html__( 'Header', 'text-domain' ),
    'icon' => 'dashicons-schedule',
] );

Kirki::add_section( 'section_id', [
    'priority'    => 1,
    'title'       => esc_html__( 'Fonts and colors', 'text-domain' ),
    'icon' => 'dashicons-editor-paragraph',
] );

Will produce the following result:

Two WordPress dashicons added to a customizer panel and a customizer section.

But how do I know which icons to choose from, you ask. The icons we use are dashicons. According to the documentation page, Dashicons is the official icon font of the WordPress admin as of 3.8. This icon font is used to supply many of the icons you see in the WordPress admin. They are also used in the TinyMCE editor for example.

With Kirki, these dashicons are utilised in the customizer. Let's have a look at the icons that can be used. Go the the documentation page. Here, you'll see all the icons.

The dash icon page for the dashicons-editor-paragraph icon.

Scroll down the list for all the icons. If you see an icon you would like to try, click it and the icon will be shown in big. Copy the name of the icon and use that for the 'icon' => 'dashicons-name' key and value pair.

This works both with sections and panels. As you see, it's incredibly easy to add icons to panels and sections in the WordPress customizer by using the Kirki Framework in a smart way.

Adding icons to default WordPress sections

This is great. But we still don't have added icons to every section yet. There are also several default WordPress sections which are already registered by default.

To add icons to these, we'll

1. deregister every section;

2. register them again with the icon.

1. Remove the default panels/sections

To deregister a WordPress customizer section, we'll use the default WordPress Customizer API.

function rjs_remove_sections_panels( $wp_customize ) {
 
    //$wp_customize->remove_panel('nav_menus');
    //$wp_customize->remove_panel('widgets');
    $wp_customize->remove_section('custom_css');
    //$wp_customize->remove_section('static_front_page');
    //$wp_customize->remove_section('title_tagline');
    //$wp_customize->remove_section('colors');
 
    //$wp_customize->remove_section('header_image'); //only with theme supports "custom-header"
    //$wp_customize->remove_section('background_image'); //only with theme supports "custom-background"
 
}
add_action( 'customize_register', 'rjs_remove_sections_panels', 50);

Remove the comment // part before each line to activate that line.

Note: in the add_action() call, the last (third) parameter is the number 50. I haven't researched why this is, but it is important to keep that parameter. For example, if you omit it, you'll not be able to remove the nav_menus panel. If anyone knows why this is, I would be grateful if you could let me know, so I can add it here (rjs@ralphjsmit.com).

2. Adding the panels again with Kirki

When you want to add the panel again, first determine whether you've used remove_section or remove_panel for each case.

In my example, I've removed the custom CSS section. Use the parameter in the remove_ call as a section id and the add the correct name and priority. You can check the below table for the title, id and priority.

Kirki::add_section( 'custom_css', [
    'priority'    => 200,
    'title'       => __( 'Additional CSS' ),
    'icon' => 'dashicons-media-code',
] );

All the default WordPress sections and panels with their respective title, id and priority. Source: WordPress Theme Handbook (titles updated by myself)

In this way, you can add icons to all the WordPress customizer panels and sections.

Conclusion

Adding dashicons to panels and sections in the WordPress customizer is extremely easy to do. Thanks to the huge library of dashicons available, there'll always be an icon that's just perfect.