Gallery

The Gallery option adds a multi-image selection control to your custom widget, allowing users to create and manage a collection of images from the WordPress Media Library. It’s designed for handling multiple images as a single group.

Why would someone use it in a custom widget? #

Use this control when your widget’s functionality depends on a set of images rather than a single one. This is essential for creating image sliders, lightbox galleries, logo carousels, portfolio grids, client showcases, or any feature that displays multiple images in a structured layout.

Where This Option Appears #

• In Widget Builder: You add this control in the Content tab.
• In the Elementor Editor: Once saved, it appears as an interactive gallery manager. Users can click “Add Images” to open the Media Library, select multiple images, and see them displayed as a thumbnail grid within the control for easy reordering or removal.

Available Settings #

Based on the provided screenshots, here are the configurable settings for the Gallery control:

Basic Settings #

• Label: The name of the control (e.g., “Image Slider”, “Portfolio Gallery”).
• Name: The unique machine-readable ID (like image_gallery) for the dynamic shortcode.
• Description: Optional text to describe the gallery’s purpose.
• The interface includes an “Add Images” button for users to build their collection. The preview shows “3 Images Selected,” indicating it displays the current state.

Advanced Settings #

• Show Label, Label Block, Responsive Control: Standard visibility and layout options. Responsive Control could allow defining different galleries or image sizes per device.
• Dynamic Support: A powerful feature. If enabled, the gallery could be populated dynamically from a source like a post’s gallery field or an ACF gallery field.
• Frontend Available: When enabled, the array of gallery image data (URLs, IDs, captions) is passed to your widget’s frontend JavaScript, which is crucial for building interactive sliders or lightboxes.
• Separator, Conditions, Control Classes, Selector: Standard advanced options.

Generated Shortcode #

When you add a Gallery control with the Name portfolio_gallery, Widget Builder generates a shortcode like: {{portfolio_gallery}}.

• What it represents: This shortcode outputs structured data for the collection of selected images. It typically provides an array or a list of image objects, each containing properties like the image URL, ID, alt text, and caption.
• Where to use it: This data is most useful in your HTML Panel (to loop through and render image tags) and critically in your JS Panel (to power sliders, lightboxes, or grids).
  • HTML/JS Panel: You would use JavaScript or the builder’s templating logic to iterate over the {{portfolio_gallery}} data and generate HTML for each image.

How to Use It: A Practical Example #

Let’s create a basic “Image Slider” widget.

1. In Widget Builder’s Content tab, add a Gallery control.
2. Set the Label to Slider Images. The Name will auto-fill as slider_images.
3. Ensure Frontend Available is enabled in the Advanced tab.
4. In your HTML panel, create a container: <div class="slider-container" id="my-slider"></div>.
5. In your JS Panel, write JavaScript to:
   • Access the gallery data from slider_images.
   • Dynamically create <img> elements for each image.
   • Append them to the slider-container.
   • Initialize a slider/carousel library (like Swiper.js, linked in the Includes panel).
6. Style the container and images in your CSS panel.

In the editor, users can add, remove, and reorder images in the gallery. Your JavaScript will use that collection to build the working slider on the front end.

Common Use Cases #

• Image Sliders & Carousels: The most common use case for displaying a rotating set of images.
• Portfolio or Project Grids: Displaying multiple project screenshots or photos in a masonry or grid layout.
• Client Logo Showcases: Creating a row or grid of client logo images.
• Lightbox Galleries: Creating a grid of thumbnails that open into a full-screen lightbox viewer.
• Dynamic Galleries: Using Dynamic Support to pull galleries from custom fields on posts or pages.

Helpful Tips #

• JavaScript is Required: Unlike the single Media control, a Gallery’s output is a data set. To display it, you will almost always need to write JavaScript in your JS Panel to process the images and generate HTML.
• Plan Your Data Structure: Understand what image properties (URL, ID, caption) the {{gallery_name}} shortcode makes available, so you can use them correctly in your code.
• Use with External Libraries: For features like sliders or lightboxes, you will need to include the corresponding JS/CSS library (e.g., Swiper, Fancybox) in the Includes panel of the Widget Builder.
• Consider Image Optimization: For galleries displaying many images, consider lazy-loading techniques in your JavaScript to improve page load performance.

The Gallery control enables the creation of rich, visual, and interactive multi-image widgets, moving beyond single images to handle curated collections.