The Visual Choice field renders a set of image cards in your widget’s panel, one per option, and the user picks by clicking a thumbnail. It is the layout-picker control. Where a Select offers words and a Choose offers icons, the Visual Choice shows a small picture of what each variant actually looks like. Inside the Master Addons Widget Builder, that makes it the natural fit for grid-versus-list decisions and any variant a screenshot explains faster than a name.
Visual Choice option values plug straight into Conditions, letting other controls follow the picked layout, and into the Twig-syntax template engine, where {% if style == "grid" %} switches the markup to match. Both guides cover the details.
The template contract matches the other choice fields: the value is the selected option’s key. What sets the Visual Choice apart is a second wiring style, the prefix class, which changes a class on the widget wrapper so your CSS can switch layouts without the template ever mentioning the field.
What the Visual Choice field does #
- Renders clickable image cards in the Elementor panel, each option defined by a key, a title, and an image.
- Holds one key from the defined set, the card currently selected.
- Lays cards out in columns, three per row by default, adjustable through the Columns option.
- Feeds templates the selected key for modifier classes and
{% if %}blocks. - Optionally sets a wrapper class through the prefix class option, so CSS alone can switch the layout.
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 team members widget with two layout variants, a 3-column grid and a stacked list, picked through thumbnail cards.
How to add a Visual Choice field #
Find Visual Choice in the fields panel on the left of the Widget Builder editor, grouped with the other choice fields.
Drag it into a section under the Content or Style tab. Layout pickers usually sit first in the panel, at the top of the Content tab, so editors choose a structure before filling in content. Once the field lands, its options open on the left.
Visual Choice field options explained #
- Label: the text shown above the cards in Elementor, for example “Layout”.
- Name: the unique identifier for the field, letters, numbers, and underscores only, for example
team_layout. - Options: each option is a key plus a title and an image. The image becomes the clickable card; the title labels it. Keys stay short and CSS-safe:
grid,list. - Columns: how many cards sit per row in the panel, 3 by default. Two large cards read better as 2 columns.
- Prefix Class: a class stem Elementor appends the selected key to and places on the widget wrapper. With
team-layout-and the keygrid, the wrapper carriesteam-layout-grid. - Default: the key selected when the widget first drops on a page.
- Description, Show Label, Separator: the standard display settings, plus Conditions for showing the field only when another control has a certain value.
Connect the Visual Choice to your widget #
Two wiring styles. Pick one per field.
Style A: template patterns. The token prints the selected key, so everything from the Select field applies. A modifier class:
<div class="team team--{{ team_layout }}">
...
</div>or a structural branch when the variants need different markup:
{% if team_layout == 'list' %}
<ul class="team-list"> ... </ul>
{% else %}
<div class="team-grid"> ... </div>
{% endif %}Style B: the prefix class. Fill in the Prefix Class option, say team-layout-, and Elementor writes team-layout-grid or team-layout-list onto the widget’s wrapper as the user clicks cards. Your CSS then targets the combined class:
.team-layout-grid .member { /* grid card rules */ }
.team-layout-list .member { /* stacked row rules */ }The template never references the field at all; the wrapper class does the switching. This keeps the HTML to a single markup block and pushes every variant into the stylesheet. When only presentation changes, that is usually the cleaner cut.
Watch out for mixing the two styles on one field. A template conditional that assumes grid while the prefix class simultaneously sets team-layout-list is two sources of truth, and they will drift, usually months later when someone edits one side and forgets the other exists. Decide whether this field speaks through the template or through the wrapper class, then stick to it.
Use the Visual Choice control in Elementor #
Add your custom widget to a page in Elementor, reloading the editor if the page was already open. The control shows your option cards in the panel, the selected one highlighted.
Click a card and the layout flips in the preview, either through your modifier class or through the prefix class on the wrapper, whichever wiring you chose. Because each card shows the variant itself, editors pick the right layout without reading a thing.
Common use cases #
- Grid versus list layouts for team, portfolio, and post widgets.
- Card style variants where thumbnails show the actual boxed, overlay, and split designs.
- Header arrangements such as image-top, image-left, and text-only hero variants.
- Slider versus static presentations of the same content set.
- Template packs inside one widget, three pre-designed looks a client picks from by picture.
Tips for working with the Visual Choice field #
- Use real screenshots as option images. A tiny render of each variant beats an abstract icon; the card is the documentation.
- Choose one wiring style per field. Template patterns or the prefix class, not both, or the two will disagree eventually.
- Keys go into class names, so keep them slugs.
gridandlist, not “Grid Layout”. - End the prefix with a separator.
team-layout-plusgridreads asteam-layout-grid; without the hyphen you getteam-layoutgrid. - Match Columns to your card count. Two options across 3 columns leaves a gap; set Columns to 2 and the row fills.
- Reserve it for visual differences. If the options differ in behavior rather than appearance, a Select with clear labels serves editors better.
Frequently Asked Questions #
What is the Visual Choice field in the Master Addons Widget Builder?
The Visual Choice field adds an image-card picker to a custom Elementor widget. Each option is a key with a title and a thumbnail image; the user clicks a card and your widget reacts, either through the selected key in the template or through a prefix class placed on the widget wrapper.
How does the prefix class work?
You set a class stem in the Prefix Class option, for example team-layout-. Elementor appends the selected key and puts the result, such as team-layout-grid, on the widget’s wrapper element. Your CSS targets that combined class to switch layouts, and the template needs no token at all.
Do I still get a template token?
Yes. {{ team_layout }} prints the selected key, so modifier classes and {% if team_layout == 'list' %} conditionals work exactly as they do with a Select. The prefix class is an alternative, not a replacement.
How many cards fit in a row?
Three by default. The Columns option changes that, so two big layout thumbnails can sit as a 2-column pair and six small style swatches can pack into 3 columns over two rows.
When should I use Visual Choice instead of Select or Choose?
When a picture identifies the option faster than a word or an icon. Layout and design variants are the classic case. For short visual sets that an eicon covers, alignment or direction, the Choose field is lighter; for wordy or long lists, use a Select.
Does the value use the option title or the key?
The key, as with every choice field. Titles and images exist for the panel; comparisons, modifier classes, and the prefix class suffix all use the key you defined.
Wrapping up #
The Widget Builder Visual Choice field lets editors pick a layout by looking at it: image cards in the panel, a key in the template, and the prefix class option when you would rather switch layouts from CSS alone. It pairs naturally with the Choose field. Thumbnails handle the big structural picks, icon buttons the small adjustments. Explore the rest of the Master Addons widgets and extensions, and see the pricing page for what each plan includes.
