Media

The Media field connects a custom widget to the WordPress media library. Drop the field in, and anyone editing the widget in Elementor gets the familiar image chooser: click, pick or upload, done. Inside the Master Addons Widget Builder, it is the field behind hero images, avatars, logos, and every other single-image slot a widget needs.

Unlike a text field, the Media field’s value is not one string. It is an array carrying the file’s url, id, alt, and more, and your template reaches each piece with dot notation. There is one friendly shortcut: printing the field directly gives you the URL. And one habit worth building from day one, guarding the markup with an {% if %} so an empty field leaves no broken image behind.

What the Media field does #

• Opens the WordPress media library from the Elementor panel, upload or pick from existing files.
• Stores the selection as an array with url, id, and alt among its keys.
• Prints the URL on a direct token: {{ hero_image }} outputs the file URL as a shortcut.
• Exposes each property by dot notation: {{ hero_image.url }}, {{ hero_image.id }}, {{ hero_image.alt }}.
• Can filter the library by media type, image, video, or audio, and supports dynamic values.

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 restaurant hero widget with a single Media field named hero_image that fills the banner.

How to add a Media field #

In the Widget Builder editor, find the Media field in the panel on the left, grouped with the other media fields.

Drag it into a section under the Content tab; an image is content, even when it ends up as a CSS background. Once it lands, the field’s options open on the left.

Media field options explained #

• Label: the text shown above the chooser in Elementor, for example “Hero Image”.
• Name: the unique identifier for the field, letters, numbers, and underscores only, for example hero_image.
• Default: a starting file as a URL and ID pair, so the widget drops onto the page already looking finished.
• Media Type: filters what the library offers, image, video, or audio, keeping editors from wiring an mp3 into an img tag.
• Dynamic: lets the value come from a dynamic source rather than a fixed pick.
• Description, Show Label, Separator: the standard display settings, plus Conditions for showing the field only when another control has a certain value.

Connect the Media field to your template #

The value is an array, and the template rules follow from that. The direct token is a shortcut for the most common need:

<img src="{{ hero_image }}">

Printing an array value directly outputs its url key, so this renders the file URL. The explicit form does the same and reads more clearly next to its siblings:

<img src="{{ hero_image.url }}" alt="{{ hero_image.alt }}">
<!-- {{ hero_image.id }} holds the attachment ID -->

Now the habit that separates tidy widgets from broken-icon widgets: the empty guard. A Media field with nothing picked renders empty attributes, and <img src=""> shows as a broken image. Wrap the markup:

{% if hero_image.url %}
<img src="{{ hero_image.url }}" alt="{{ hero_image.alt }}">
{% endif %}

The field works in the CSS tab too. A background slot is one line:

.hero-banner {
  background-image: url('{{ hero_image }}');
}

Watch out for alt text passing through untouched. {{ hero_image.alt }} prints whatever the media library holds, and libraries are full of images with empty alt fields. The guard keeps the attribute present but it cannot invent the text. Widgets built for clients deserve a note telling editors to fill alt text in the library.

Use the Media control in Elementor #

Add your custom widget to a page in Elementor, reloading the editor if the page was already open. The Media field renders as Elementor’s standard image chooser box under your label.

Click the box and the WordPress media library opens, filtered to the media type you set. Pick or upload a file, confirm, and the preview updates the moment the selection lands.

Swapping the image later is the same click. Removing it empties the value, which is exactly the case your {% if %} guard covers.

Common use cases #

• Hero and banner images, as an img tag or a CSS background.
• Avatars and headshots in testimonial and team widgets.
• Logos in header, footer, and client-strip widgets.
• Card thumbnails where each widget instance features one image.
• Decorative section backgrounds set through background-image in the CSS tab.

Tips for working with the Media field #

• Always guard with {% if hero_image.url %}. An unset field otherwise renders an empty src and a broken-image icon.
• Print the alt. alt="{{ hero_image.alt }}" costs nothing and carries the library’s alt text into your markup.
• Use the direct token for CSS backgrounds. url('{{ hero_image }}') keeps the CSS tab readable.
• Set a default image. A widget that drops onto the page with a real photo sells itself; a gray placeholder does not.
• Filter with Media Type. If the slot is an image, say so, and the library will not offer videos.
• Remember the shortcut is url-only. Any property other than the URL needs dot notation; there is no shortcut for id or alt.

Frequently Asked Questions #

Wrapping up #

The Widget Builder Media field is the single-image workhorse. A library picker in the panel, a URL shortcut in the template, dot notation for id and alt, and an {% if %} guard standing between your widget and a broken-image icon. When one image becomes many, move up to the Gallery field and its loop. Explore the rest of the Master Addons widgets and extensions, and see the pricing page for what each plan includes.