Media

The Media option adds a media upload and selection control to your custom widget, allowing users to choose files from the WordPress Media Library or upload new ones. It’s the primary way to handle images, videos, audio, and other supported file types.

Why would someone use it in a custom widget? #

Use this control whenever your widget needs to include an image, video, document, or any other media file. This is essential for creating image banners, logo uploaders, background video sections, PDF download buttons, or any widget where visual or file-based content is central.

2. Where This Option Appears #

• In Widget Builder: You add this control in the Content tab.
• In the Elementor Editor: Once saved, it appears as a standard Elementor media upload button. Clicking it opens the familiar WordPress Media Library dialog for selection.

3. Available Settings #

Here are the configurable settings for the Media control:

Basic Settings #

• Label: The name of the control (e.g., “Background Image”, “Company Logo”).
• Name: The unique machine-readable ID (like bg_image) for the dynamic shortcode.
• Description: Optional text to guide the user.
• Media Types: A critical multi-select option. This defines what type of files users can pick:
  • Image: Allows selection of standard image files (JPG, PNG, GIF, etc.).
  • Video: Allows selection of video files (MP4, MOV, etc.).
  • Other Types: May include audio, PDF, or other document formats. By default, it is often set to Image only.

Advanced Settings #

• Show Label, Label Block, Responsive Control: Standard options. Responsive Control is especially useful for images, allowing different images to be set for different devices.
• Dynamic Support: A powerful feature. When enabled, the media field can be populated dynamically from sources like a post’s Featured Image, an ACF Image field, or site logo.
• Frontend Available: If enabled, the media attachment data (URL, ID, alt text) is passed to your widget’s JavaScript.
• Separator, Conditions, Control Classes, Selector: Standard advanced options.

Generated Shortcode #

When you add a Media control with the Name hero_image, Widget Builder generates the shortcode: {{hero_image}}.

• What it represents: This shortcode typically outputs the URL of the selected media file (e.g., https://yoursite.com/wp-content/uploads/2025/12/hero.jpg). In some implementations, it might output the attachment ID or an object containing multiple properties.
• Where to use it:
  • HTML Panel: Use it in src or href attributes: <img src="{{hero_image}}" alt=""> or <video src="{{background_video}}">.
  • CSS Panel: Use it for background images: background-image: url('{{hero_image}}');.

How to Use It: A Practical Example #

Let’s create a simple “Hero Banner” widget with a background image.

1. In Widget Builder’s Content tab, add a Media control.
2. Set the Label to Background Image. The Name will auto-fill as background_image.
3. In Media Types, ensure Image is selected.
4. In your HTML panel, create a container: <div class="hero-banner"></div>.
5. In your CSS panel, apply the image:

.hero-banner {
    background-image: url('{{background_image}}');
    background-size: cover;
    min-height: 500px;
}

Now, users can upload or select any image from their library, and it will automatically become the banner’s background.

Common Use Cases #

• Image Displays: For logos, profile pictures, product images, and banners.
• Background Media: Setting background images or videos for sections.
• File Downloads: Creating a button to download a PDF, brochure, or other document (using the URL in a link).
• Dynamic Images: Using Dynamic Support to automatically pull the current post’s featured image into a blog post grid or single post widget.

Helpful Tips #

• Restrict Media Types: Use the Media Types setting wisely. If your widget is designed for an image, limit it to Image only to prevent user confusion.
• Consider Responsive Images: For important images, consider enabling Responsive Control or creating separate controls (e.g., image_tablet, image_mobile) to allow optimization for different screen sizes.
• Handle Dynamic Data: When using Dynamic Support, your widget’s code should gracefully handle cases where a dynamic source might be empty (e.g., a post with no featured image).
• Output Might Be an ID: Depending on the builder’s configuration, the shortcode might output the attachment ID instead of the URL. If you need the URL in your HTML/CSS and get an ID, you may need to use a specific dynamic tag format like {{hero_image.url}} – check the builder’s documentation for the exact syntax.

The Media control connects your widget directly to the user’s rich media library, making it easy to build visually dynamic and content-rich components.