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 row arrays, each with three keys. Returns an empty array [] when no images have been selected.

php

$gallery = themeplus_get_option( 'hero_gallery', [] );
// Returns:
// [
//     [ 'id' => 42, 'url' => 'https://example.com/.../image-1.jpg', 'alt' => 'Alt text' ],
//     [ 'id' => 43, 'url' => 'https://example.com/.../image-2.jpg', 'alt' => '' ],
//     [ 'id' => 44, 'url' => 'https://example.com/.../image-3.jpg', 'alt' => 'Third image' ],
// ]

---

Usage Examples

Basic gallery output

php

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

if ( ! empty( $gallery ) ) {
    echo '<div class="gallery-grid">';
    foreach ( $gallery as $image ) {
        echo '<img src="' . esc_url( $image['url'] ) . '" alt="' . esc_attr( $image['alt'] ) . '" class="gallery-grid__item" loading="lazy">';
    }
    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 ) {
        echo '<div class="swiper-slide">';
        echo '<img src="' . esc_url( $image['url'] ) . '" alt="' . esc_attr( $image['alt'] ) . '">';
        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 ) {
        $thumb_url = wp_get_attachment_image_url( $image['id'], 'medium' );

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

Getting image data for a script

php

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

foreach ( $gallery as $image ) {
    $image_data[] = [
        'id'  => $image['id'],
        'url' => $image['url'],
        'alt' => $image['alt'],
    ];
}

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

• Each item in the returned array has three keys: id (int), url (string — full size URL), and alt (string). Use $image['url'] for direct output, or $image['id'] with wp_get_attachment_image_url() when you need a specific image size other than full.
• Always check ! empty( $gallery ) before looping — the field returns an empty array when no images are selected.
• The url key always returns the full-size URL. Use wp_get_attachment_image_url( $image['id'], 'medium' ) when you need a resized version, such as thumbnails in a lightbox.
• For selecting a single image only, use the Image field instead.