Gallery

The Gallery field allows users to select and manage multiple images using the WordPress Media Library. It’s perfect for creating image sliders, portfolios, product galleries, or any layout that requires more than one image.

This field returns an array of image objects, each containing the image ID and URL, giving you complete flexibility in how the images are displayed.

Settings

1. Field Type: Selects the type of input field to display. The Gallery field opens a media selector that allows users to pick multiple images at once.
2. Field Label: The label displayed above the field. Helps users understand that they can upload or select more than one image.
3. Field Name: A unique identifier used in the database and code. Only lowercase letters, numbers, and underscores are allowed. This value is used when retrieving and saving data.
4. Required Field: Forces users to select at least one image before submitting the form. If enabled, leaving the gallery empty will not be allowed. Defaults to off.
5. Default Value: Allows you to pre-fill the gallery with a set of images (using their IDs).
6. Placeholder: Shown when no images have been selected. Can be an icon, label, or note.
7. Image Size: Defines the size of the preview thumbnails and the size used when displaying the images on the frontend. Can be thumbnail, medium, large, full, or any registered custom size.

Frontend Value Example

When retrieved, the field returns an array of image objects:

Array
(
    [0] => Array
        (
            [id] => 255
            [url] => https://voxycure-framework.local/wp-content/uploads/2025/07/wp_dummy_content_generator_254.jpg
        )

    [1] => Array
        (
            [id] => 247
            [url] => https://voxycure-framework.local/wp-content/uploads/2025/07/wp_dummy_content_generator_246.jpg
        )
)

Each item includes:

• id – The media attachment ID.
• url – The direct link to the image file (default size or selected preview size).

Template usage

Basic Gallery Display

$gallery = get_post_meta( $post->ID, 'gallery_field_key', true );

if ( ! empty( $gallery ) && is_array( $gallery ) ) {
    echo '<div class="custom-gallery">';
    foreach ( $gallery as $image ) {
        echo '<img src="' . esc_url( $image['url'] ) . '" alt="">';
    }
    echo '</div>';
}

Advanced Display with Image Size Control

If you want to use a specific image size (like medium, large, or a custom size), use the image id:

$gallery = get_post_meta( $post->ID, 'gallery_field_key', true );

if ( ! empty( $gallery ) && is_array( $gallery ) ) {
    echo '<div class="custom-gallery">';
    foreach ( $gallery as $image ) {
        $image_data = wp_get_attachment_image_src( $image['id'], 'medium' ); // Change to desired size
        if ( $image_data ) {
            echo '<img src="' . esc_url( $image_data[0] ) . '" alt="">';
        }
    }
    echo '</div>';
}

That’s it! You’ve successfully configured a Gallery field. Now it’s ready to handle multi-image selections and display them beautifully in your WordPress setup.