Image Gallery Control for the Customizer

Authored by

The Customize Image Gallery Control plugin adds a new control type to the customizer: image_gallery. This control populates its associated setting with an array of the selected image (attachment) IDs.

What’s Image Gallery Control good for?

Currently the customizer provides media controls that only allow one image to be selected. If multiple images are needed, each one of them would need to have a separate control and setting created statically. The image_gallery control allows you to select multiple images via the Media Library in the same way as you select images for a gallery in a post. Just as you can see a preview of the selected images for the gallery in the content editor, so too can you see a preview of the selected images icons right in the customizer control as well, without needing to open the Media Library to find out which images have been selected.

Image Gallery field in the customizer
Selecting multiple images in Media Library.


The Image Gallery control extends WP_Customize_Control PHP class as CustomizeImageGalleryControl\Control, and in JS it extends wp.customize.Control as wp.customize.ImageGalleryControl (and aliased as wp.customize.controlConstructor.image_gallery). The control uses existing functionality of WordPress Media Library and populates its setting with an array of IDs for the selected image attachment posts, similar to how the ids attribute is populated on the gallery shortcode. The next time you use the customizer and open Media Library to modify the same image gallery field, you’ll see the previously saved images sorted to top.

How to use the Image Gallery Control?

Just enabling the plugin won’t make any visible changes to the customizer right away: you’ll need to integrate it into your plugin or theme. Lets say you want to add an extra Image Gallery section to the customizer with the control. For that you’ll need to do a few things: register a new customizer section (if you don’t want to re-use an existing one), register a new setting with wp_parse_id_list as the sanitize_callback, and register the control.

A sample function to add the section, setting, and control:

function featured_image_gallery_customize_register( $wp_customize ) {

	if ( ! class_exists( 'CustomizeImageGalleryControl\Control' ) ) {

	$wp_customize->add_section( 'featured_image_gallery_section', array(
		'title'      => __( 'Gallery Section' ),
		'priority'   => 25,
	) );
	$wp_customize->add_setting( 'featured_image_gallery', array(
		'default' => array(),
		'sanitize_callback' => 'wp_parse_id_list',
	) );
	$wp_customize->add_control( new CustomizeImageGalleryControl\Control(
			'label'    => __( 'Image Gallery Field Label' ),
			'section'  => 'featured_image_gallery_section',
			'settings' => 'featured_image_gallery',
			'type'     => 'image_gallery',
	) );
add_action( 'customize_register', 'featured_image_gallery_customize_register' );

And there you have it:

Sample Image Gallery Implementation

Now you can use the newly created control and setting in your themes/plugins, for example by using the WordPress built-in gallery shortcode.

Function for displaying the gallery:

// In your functions.php file or some plugin's file.
function the_featured_image_gallery( $atts = array() ) {
	$setting_id = 'featured_image_gallery';
	$ids_array = get_theme_mod( $setting_id );
	if ( is_array( $ids_array ) && ! empty( $ids_array ) ) {
		$atts['ids'] = implode( ',', $ids_array );
		echo gallery_shortcode( $atts );

Use the function in a template or any place where it needs to be displayed, such as in front-page.php:

<?php the_featured_image_gallery(); ?>

Creating a shortcode for featured_image_gallery

function featured_image_gallery_shortcode( $atts ) {
	$ids_array = get_theme_mod( 'featured_image_gallery' );
	if ( is_array( $ids_array ) && ! empty( $ids_array ) ) {
		$ids = implode( ',', $ids_array );
		$atts['include'] = $ids;
	return gallery_shortcode( $atts );
add_shortcode( 'featured_image_gallery', 'featured_image_gallery_shortcode' );

Now you can just use the shortcode within your posts and pages: [featured_image_gallery]

13 thoughts on “Image Gallery Control for the Customizer”

  1. Hi,

    Firstly this is great custom control ever, amazing! thanks..

    But I get issue here, images always displayed randomly ( random ) in Image Gallery field in the customizer when I close customizer and go back to customizer . You can try it yourself.

    Let me know if you have any solutions… 🙂

  2. Hey,

    Thanks for reaching out with the issue. The plugin is now updated to display images in a consistent order. The images in the control will be displayed in the same order as in media library.


  3. Hey Miina,

    This is a great plugin! Do you know if there is a way to output different size images, other than thumbnails? It would also be nice to be able to change the number of columns.


    1. Hey Troy,

      Thanks for reaching out and sorry for the late answer, I was on time off for some time.

      The sample shortcode created in the post should accept the same attributes as the default gallery shortcode, including size and columnsattributes. For example you could use the shortcode like this: [featured_image_gallery size="full" columns="4"] .

      Hope that works for you.


  4. Hi Josh,

    Thanks for reaching out.

    Within the article there is a description about how to implement the plugin, under “How to use the Image Gallery Control?”.

    You can download the plugin from here:

    If you tried following the sample already and ran into issues while installing it, could you please describe in more detail what kind of advice do you need?


  5. `$atts[‘include’] = $ids;` results in this warning when using the shortcode:

    Warning: Illegal string offset ‘include’ in /Users/sridharkatakam/Sites/local/wp-content/themes/genesis-sample/functions.php on line 170

    Replacing that with

    $atts = shortcode_atts( array(
    ‘include’ => $ids
    ), $atts );


    `$atts = [‘include’ => $ids];` should fix it.

  6. This control returns an array of attachments ids. If you want the src of each of the images, you could do something like this:
    Customizer setting = ‘section-images’

    $images_id = get_theme_mod(‘section-images’, []);
    $images_url = array_map(“wp_get_attachment_url”, $images_id);

    This will store every image url in the $images_url array

    Now i would like to know, is there a way to remove an image from the control?

  7. Dear Miina

    We have modified the customizer control. We would like to use in our theme on the WordPress directory and I would like to know if it is possible and which credits should we include.

    We haven’t found a license in the projects.

    Thank you

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.