Using WordPress ‘post_gallery’ PHP filter

by

The post_gallery WordPress PHP filter allows you to modify the default gallery shortcode output. If the filtered output isn’t empty, it will be used instead of generating the default gallery template.

Usage

add_filter('post_gallery', 'your_custom_function', 10, 3);

function your_custom_function($output, $attr, $instance) {
    // Your custom code here
    return $output;
}

Parameters

  • $output (string) – The gallery output. Default empty.
  • $attr (array) – Attributes of the gallery shortcode.
  • $instance (int) – Unique numeric ID of this gallery shortcode instance.

More information

See WordPress Developer Resources: post_gallery

Examples

Change the default gallery output by creating a custom HTML structure.

add_filter('post_gallery', 'custom_gallery_html', 10, 3);

function custom_gallery_html($output, $attr, $instance) {
    // Retrieve the images from the gallery
    $ids = explode(',', $attr['ids']);

    $output = '<div class="custom-gallery">';

    foreach ($ids as $id) {
        $image_src = wp_get_attachment_image_src($id, 'thumbnail');
        $output .= '<img src="' . $image_src[0] . '" alt="">';
    }

    $output .= '</div>';

    return $output;
}

Display image captions below each image in the gallery.

add_filter('post_gallery', 'add_captions_to_gallery', 10, 3);

function add_captions_to_gallery($output, $attr, $instance) {
    $ids = explode(',', $attr['ids']);
    $output = '<div class="gallery-with-captions">';

    foreach ($ids as $id) {
        $image_src = wp_get_attachment_image_src($id, 'thumbnail');
        $image_caption = wp_get_attachment_caption($id);
        $output .= '<div class="gallery-item">';
        $output .= '<img src="' . $image_src[0] . '" alt="">';
        $output .= '<p class="caption">' . $image_caption . '</p>';
        $output .= '</div>';
    }

    $output .= '</div>';

    return $output;
}

Add a lightbox feature to the default gallery output.

add_filter('post_gallery', 'add_lightbox_to_gallery', 10, 3);

function add_lightbox_to_gallery($output, $attr, $instance) {
    $ids = explode(',', $attr['ids']);
    $output = '<div class="gallery-with-lightbox">';

    foreach ($ids as $id) {
        $image_src_thumb = wp_get_attachment_image_src($id, 'thumbnail');
        $image_src_full = wp_get_attachment_image_src($id, 'full');
        $output .= '<a href="' . $image_src_full[0] . '" data-lightbox="gallery">';
        $output .= '<img src="' . $image_src_thumb[0] . '" alt="">';
        $output .= '</a>';
    }

    $output .= '</div>';

    return $output;
}

Create a slider using the gallery images.

add_filter('post_gallery', 'gallery_to_slider', 10, 3);

function gallery_to_slider($output, $attr, $instance) {
     $ids = explode(',', $attr['ids']);
     $output = '';

     foreach ($ids as $id) {
         $image_src = wp_get_attachment_image_src($id, 'large');
         $output .= '';
         $output .= '';
         $output .= '';
     }

     $output .= '';

     return $output;
}

Restrict the number of images shown in the gallery to a specific count.

add_filter('post_gallery', 'limit_gallery_images', 10, 3);

function limit_gallery_images($output, $attr, $instance) {
    $ids = explode(',', $attr['ids']);
    $limit = 5; // Set the number of images to display
    $output = '';

    for ($i = 0; $i < $limit && $i < count($ids); $i++) {
        $id = $ids[$i];
        $image_src = wp_get_attachment_image_src($id, 'thumbnail');
        $output .= '';
    }

    $output .= '';

    return $output;
}