Image Gallery Control for the Customizer

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.

Implementation

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' ) ) {
		return;
	}

	$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(
		$wp_customize,
		'featured_image_gallery',
		array(
			'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:

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]