The Gallery field lets an editor hand your widget a whole set of images in one move: open the media library, select ten photos, done. Inside the Master Addons Widget Builder, it is the field for portfolio grids, photo walls, and carousels, anywhere the image count belongs to the site owner rather than the widget author.
Because the value is an array of images, the connection to your HTML is a loop, not a token. A {% for %} block prints your image markup once per photo, in the order the gallery holds them. Ten photos render ten items. Add two more from the panel and two more items appear, no template changes.
What the Gallery field does #
- Opens the WordPress media library in multi-select mode from the Elementor panel.
- Stores an ordered array of images, each carrying its
idandurl. - Feeds your template through a
{% for %}loop, one iteration per image. - Leaves layout to your CSS: the loop prints items, the grid wraps them.
- Supports a default image set and dynamic values, so the widget can ship pre-filled.
If you are new to building widgets, start with the Widget Builder overview first.
Before you start #
- WordPress with Elementor installed and active.
- Master Addons for Elementor installed and active. New to the plugin? See the installation guide.
- A custom widget open in the Widget Builder editor. Our example is a photography portfolio widget that renders a 3-column grid, one cell per gallery image.
How to add a Gallery field #
Find the Gallery field in the panel on the left of the Widget Builder editor, grouped with the other media fields.
Drag it into a section under the Content tab. Once it lands, the field’s options open on the left.
Gallery field options explained #
- Label: the text shown above the control in Elementor, for example “Portfolio Images”.
- Name: the unique identifier for the field, letters, numbers, and underscores only. Your loop refers to this name, for example
portfolio_gallery. - Default: a starting set of images, so the grid has something to show the moment the widget is dropped.
- Dynamic: lets the image set come from a dynamic source rather than a hand-picked selection.
- Description, Show Label, Separator: the standard display settings, plus Conditions for showing the field only when another control has a certain value.
Connect the Gallery to your HTML with a loop #
The Gallery has no single-value token. Its value is an array of media items, so the template wraps the per-image markup in a {% for %} block, the same shape a Repeater uses:
<div class="portfolio-grid">
{% for img in portfolio_gallery %}
<figure class="portfolio-cell">
<img src="{{ img.url }}">
</figure>
{% endfor %}
</div>portfolio_galleryis the field’s Name.imgis a loop variable you invent; call it anything.- Each item exposes its properties by dot notation:
{{ img.url }}for the file URL,{{ img.id }}for the attachment ID. - The block prints once per image, in the gallery’s order.
An empty gallery loops zero times, which is usually the behavior you want. The wrapper div still renders, though, and an empty container with padding or a border shows up as a mysterious gray box on the page. When an empty gallery should leave nothing behind, guard the whole block:
{% if portfolio_gallery %}
<div class="portfolio-grid"> ... </div>
{% endif %}Watch out for reaching for a bare {{ portfolio_gallery }} out of habit. On a Media field that shortcut prints a URL; here the value is a list of images, and only the loop gets at them. If your grid renders empty while the panel clearly holds photos, the missing {% for %} is almost always why.
Layout stays in the CSS tab. A grid container such as grid-template-columns: repeat(3, 1fr) wraps however many cells the loop produces, so twelve photos make four rows without either the template or the editor thinking about it.
Use the Gallery control in Elementor #
Add your custom widget to a page in Elementor, reloading the editor if the page was already open. The Gallery field renders as an add-images box under your label, with thumbnails of the current set once one exists.
Click it and the media library opens in multi-select mode. Pick the set, confirm, and the grid fills in the preview. Reopening the gallery lets the editor add, remove, and reorder images, and the page follows the new order on the next render.
Common use cases #
- Portfolio and photography grids, one cell per image, CSS grid handling the rows.
- Lightbox collections where each loop item links its full-size URL for a lightbox script.
- Image carousels, the loop prints slides and the widget’s JS tab runs the slider.
- Client logo walls maintained by the site owner without touching the widget.
- Before-and-after or project galleries that grow with each finished job.
Tips for working with the Gallery field #
- The loop is the connection. There is no useful direct print of a gallery; only
{% for %}…{% endfor %}reaches the images. - Use
{{ img.url }}inside the loop. Each item is a media array, and dot notation picks out the URL and ID. - Let CSS own the layout. A grid with fixed columns absorbs any image count; the template stays a single figure block.
- Guard the wrapper when empty means invisible.
{% if portfolio_gallery %}keeps an unfilled widget from rendering an empty container. - Ship a default set. Even three placeholder photos make the widget legible on first drop.
- Reorder in the panel, not the template. The loop follows gallery order, so drag the thumbnails and the page rearranges itself.
Frequently Asked Questions #
What is the Gallery field in the Master Addons Widget Builder?
The Gallery field adds a multi-image media library picker to a custom Elementor widget. The selection is stored as an ordered array of images, each with its id and url, and your template prints them with a {% for %} loop, one iteration per image.
How do I display the gallery images in my HTML?
Wrap the per-image markup in a loop: {% for img in portfolio_gallery %}<img src="{{ img.url }}">{% endfor %}, where portfolio_gallery is the field’s Name. The block renders once per image in gallery order.
Why does my gallery print nothing?
Check for a bare token first. {{ portfolio_gallery }} does not print an image list; the value is an array of items and only a {% for %} loop reads it. Inside the loop, make sure you use {{ img.url }} rather than the loop variable alone if the URL is what you need explicitly.
How does the grid handle more images?
That is the widget CSS’s job. A container with, say, repeat(3, 1fr) columns wraps the fourth image to a new row automatically. The loop just outputs cells; the stylesheet decides how they flow.
Can editors reorder the images?
Yes. Reopening the gallery in the Elementor panel allows adding, removing, and dragging images into a new order, and the loop renders them in exactly that order.
Should I use Gallery or a Repeater with an image sub-field?
Gallery when the items are images and nothing else, it is one picker and one loop. Reach for a Repeater when every image needs companions, a caption field, a link, a category tag, since each Repeater row can carry those extra sub-fields alongside the photo.
Wrapping up #
The Widget Builder Gallery field turns a widget into a container the site owner fills: multi-select in the library, a {% for %} loop in the template, and CSS deciding how the set flows. For single-image slots, its sibling the Media field covers heroes, avatars, and logos with the same dot-notation rules. Explore the rest of the Master Addons widgets and extensions, and see the pricing page for what each plan includes.
