Background

The Background option is a comprehensive control that adds Elementor’s full native background styling panel to your custom widget. It allows users to apply solid colors, gradients, images, or videos as backgrounds, with complete control over properties like position, repeat, size, and attachment.

Why would someone use it in a custom widget? #

Use this control when you need to give users complete design authority over a container’s background. This is essential for creating hero sections, colored content boxes, image-background containers, or any widget where the background is a key visual component, providing the same powerful interface found in core Elementor sections and columns.

Where This Option Appears #

• In Widget Builder: You add this control in the Content tab.
• In the Elementor Editor: Once saved, it appears as the standard, multi-tab Elementor background panel (Classic, Gradient, Video). Users can switch between background types and access all related settings.

Available Settings #

Here are the configurable settings for the Background control:

Basic Settings #

• Label: The name of the control (e.g., “Container Background”, “Hero Background”).
• Name: The unique machine-readable ID (like section_bg) for the dynamic shortcode.
• Description: Optional guiding text.
• Types: A critical multi-select option. This defines which background types are available to the user:
  • Classic: For solid colors and background images.
  • Gradient: For linear or radial gradient backgrounds.
  • Video: For background videos (may be an option).
• Includes/Excludes: Advanced filters to show or hide specific sub-fields within the selected background types. For example, you could Exclude the Image field from the Classic type if your widget should only use color backgrounds.

Advanced Settings #

• Show Label, Label Block, Responsive Control: Standard options. Responsive Control is especially powerful here, allowing different backgrounds (e.g., a color on mobile, an image on desktop) per device.
• Dynamic Support: When enabled, background properties (like color or image) can be populated from dynamic sources.
• Frontend Available, Separator, Conditions, Control Classes, Selector: Standard advanced options. The Selector defines the CSS class of the element that will receive the background styles.

Generated Shortcode & Function #

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

• What it represents: Similar to the Typography and Box Shadow controls, this shortcode is a dynamic tag generator. It does not output a simple value.
• How it works: After you configure the control with a Selector, the builder automatically generates all the necessary CSS rules (background-color, background-image, background-size, etc.) based on the user’s selections in the editor and applies them to the targeted element. You do not manually place this shortcode in your CSS.

How to Use It: A Practical Example #

Let’s create a “Hero Section” widget with a flexible background.

1. In Widget Builder’s Content tab, add a Background control.
2. Set the Label to Main Background.
3. In the Selector field, enter the class of your hero container, for example: .hero-container.
4. In Types, enable both Classic and Gradient.
5. In your HTML panel, ensure your hero has the matching:
   html<div class="hero-container"> <h1>Your Title Here</h1> </div>
6. The builder handles the CSS automatically.

In the editor, users can choose between a solid color, upload a background image, or create a custom gradient for the hero, using the full suite of background settings.

6. Common Use Cases #

• Section & Container Styling: The primary use for styling the background of any wrapper or content box.
• Hero Banners: Creating full-width banners with image or gradient backgrounds.
• Testimonial or Quote Boxes: Applying distinctive colored or image backgrounds to make content stand out.
• Interactive Backgrounds: Using hover conditions or dynamic data to change backgrounds.

7. Helpful Tips #

• The Selector is Essential: Correctly setting the Selector is mandatory for this control to function. It must match the class of the element you want to style.
• Tailor with Types/Excludes: Use Types and Excludes to create a simplified interface. For a simple colored header widget, you might enable only the Classic type and Exclude the Image field, leaving just the color picker.
• Default Excludes: Note that the screenshot shows Image is excluded by default. If you need background images, you must explicitly remove it from the Excludes list.
• Leverage Responsive Design: Always consider enabling Responsive Control so users can optimize backgrounds for different devices (e.g., a simpler color on mobile instead of a complex image).

The Background control integrates the complete, professional background styling system of Elementor directly into your custom widget, enabling sophisticated visual designs without manual CSS coding.