WordPress Shortcode to create an interactive gallery

Displaying a collection of images on your WordPress site can significantly enhance the visual appeal and user engagement. With the help of a simple shortcode, you can add an interactive photo gallery anywhere on your site. In this tutorial, we will create a shortcode that allows you to easily display a gallery of images from your WordPress Media Library.

Understanding the Gallery Shortcode

A gallery shortcode in WordPress serves as a placeholder within your posts and pages, which is replaced with a grid of images from your media library. It’s a convenient way to add a professional-looking photo gallery without needing additional plugins.

Step 1: Prepare Your Images

Before we dive into the code, make sure you have uploaded the images you want to display to the WordPress Media Library. Organize your images by assigning them to specific categories or tags to make them easier to retrieve programmatically.

Step 2: Write the Shortcode Function

Now, let’s get to coding. Insert the following function into your theme’s functions.php file:

function custom_gallery_shortcode($atts) {
    // Shortcode attributes for customizing the gallery
        'ids' => '', // A comma-separated list of image IDs from the Media Library
        'size' => 'thumbnail', // Image size: thumbnail, medium, large, or full
    ), $atts));

    // Convert 'ids' list into an array
    $image_ids = explode(',', $ids);
    $output = '<div class="custom-gallery">';

    // Loop through the image IDs and generate the gallery HTML
    foreach ($image_ids as $image_id) {
        $img_src = wp_get_attachment_image_src($image_id, $size);
        $img_alt = get_post_meta($image_id, '_wp_attachment_image_alt', true);
        $output .= '<a href="' . esc_url($img_src[0]) . '" class="gallery-item">';
        $output .= '<img src="' . esc_url($img_src[0]) . '" alt="' . esc_attr($img_alt) . '" />';
        $output .= '</a>';

    $output .= '</div>';

    // Return the gallery HTML to be replaced with the shortcode
    return $output;

Step 3: Register the Shortcode

After defining the function, you need to hook it up with WordPress:

add_shortcode('custom_gallery', 'custom_gallery_shortcode');

Step 4: Implement Your Gallery

You can now add your custom gallery to any post or page using the shortcode:

[custom_gallery ids="1,2,3" size="medium"]

Replace 1,2,3 with the actual IDs of the images you wish to display and choose the appropriate size.

Step 5: Style Your Gallery

To make your gallery look good, add some CSS to your theme’s stylesheet:

.custom-gallery {
    display: flex;
    flex-wrap: wrap;
    gap: 10px; /* Adjust the space between images */

.custom-gallery .gallery-item {
    flex: 1 1 calc(33.333% - 10px); /* Three images per row */
    box-shadow: 0 2px 5px rgba(0,0,0,0.2);

.custom-gallery .gallery-item img {
    width: 100%;
    height: auto;
    display: block;

This CSS is a basic starting point. You can customize it further to match your site’s design.

Best Practices and Accessibility

When creating a gallery, always ensure to:

  • Use proper alt text for images for accessibility.
  • Test the gallery on various devices and screen sizes.
  • Consider adding lightbox functionality for a full-size view.