Gallery Field

Overview

The Gallery field opens the WordPress media library and lets the user select or upload multiple images at once. It returns an array of attachment IDs. Use it for photo galleries, image sliders, portfolio grids, background image collections, or any other multi-image option in your theme.

---

Field Registration

php

[
    'id'      => 'hero_gallery',
    'type'    => 'gallery',
    'title'   => __('Hero Gallery', 'your-textdomain'),
    'subtitle' => __('Images displayed in the hero slider', 'your-textdomain'),
    'default' => [],
]

---

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be gallery
title	string	✅	Label shown above the field
subtitle	string	—	Smaller descriptive text shown below the label
desc	string	—	Help text shown below the gallery selector
default	array	—	Default value — typically an empty array
required	array	—	Conditional logic rules — see Conditional Logic

---

Return Value

Type: array

Returns an array of WordPress attachment IDs as integers, or an empty array if no images have been selected.

php

$gallery = themeplus_get_option( 'hero_gallery', [] );
// Returns: [42, 43, 44, 45]

---

Usage Examples

Basic gallery output

php

$gallery = themeplus_get_option( 'hero_gallery', [] );

if ( ! empty( $gallery ) ) {
    echo '<div class="gallery-grid">';
    foreach ( $gallery as $image_id ) {
        echo wp_get_attachment_image( $image_id, 'large', false, [
            'class' => 'gallery-grid__item',
        ]);
    }
    echo '</div>';
}

Image slider

php

$slides = themeplus_get_option( 'hero_gallery', [] );

if ( ! empty( $slides ) ) {
    echo '<div class="hero-slider swiper">';
    echo '<div class="swiper-wrapper">';
    foreach ( $slides as $image_id ) {
        $image_url = wp_get_attachment_image_url( $image_id, 'full' );
        echo '<div class="swiper-slide">';
        echo '<img src="' . esc_url( $image_url ) . '" alt="' . esc_attr( get_post_meta( $image_id, '_wp_attachment_image_alt', true ) ) . '">';
        echo '</div>';
    }
    echo '</div>';
    echo '</div>';
}

Gallery with lightbox support

php

$gallery = themeplus_get_option( 'portfolio_gallery', [] );

if ( ! empty( $gallery ) ) {
    echo '<div class="portfolio-gallery">';
    foreach ( $gallery as $image_id ) {
        $full_url    = wp_get_attachment_image_url( $image_id, 'full' );
        $thumb_url   = wp_get_attachment_image_url( $image_id, 'medium' );
        $alt         = get_post_meta( $image_id, '_wp_attachment_image_alt', true );

        echo '<a href="' . esc_url( $full_url ) . '" class="gallery-item" data-lightbox="portfolio">';
        echo '<img src="' . esc_url( $thumb_url ) . '" alt="' . esc_attr( $alt ) . '">';
        echo '</a>';
    }
    echo '</div>';
}

Getting image data for a script

php

$gallery    = themeplus_get_option( 'hero_gallery', [] );
$image_data = [];

foreach ( $gallery as $image_id ) {
    $image_data[] = [
        'id'  => $image_id,
        'url' => wp_get_attachment_image_url( $image_id, 'full' ),
        'alt' => get_post_meta( $image_id, '_wp_attachment_image_alt', true ),
    ];
}

wp_localize_script( 'your-slider-script', 'heroGallery', $image_data );

With a conditional field

php

[
    'id'      => 'enable_hero_slider',
    'type'    => 'toggle',
    'title'   => __('Enable Hero Slider', 'your-textdomain'),
    'default' => false,
],
[
    'id'       => 'hero_gallery',
    'type'     => 'gallery',
    'title'    => __('Slider Images', 'your-textdomain'),
    'subtitle' => __('Add images for the hero slider', 'your-textdomain'),
    'required' => ['enable_hero_slider', '==', true],
],

---

Notes

• The field returns an array of attachment IDs — always use WordPress functions like wp_get_attachment_image() or wp_get_attachment_image_url() to retrieve image data.
• Always check ! empty( $gallery ) before looping — the field returns an empty array when no images are selected.
• Use wp_get_attachment_image() over plain <img> tags where possible — it handles srcset, sizes, lazy loading, and accessibility attributes automatically.
• For selecting a single image only, use the Image field instead.