Elementor Controls Reference

1. Controls Overview

Controls are the fields in the Elementor editor panel that allow users to configure widgets. Every control must live inside a section.

Basic pattern:

$this->start_controls_section('section_id', [
    'label' => esc_html__('Section', 'textdomain'),
    'tab' => \Elementor\Controls_Manager::TAB_CONTENT, // or TAB_STYLE
]);

$this->add_control('control_id', [
    'label' => esc_html__('Label', 'textdomain'),
    'type' => \Elementor\Controls_Manager::TEXT,
    'default' => '',
]);

$this->end_controls_section();

Control base classes:

Base Class	Purpose	Examples
Base_Data_Control	Controls that store a single value	TEXT, SELECT, COLOR, SWITCHER, NUMBER
Control_Base_Multiple	Controls returning arrays	URL, MEDIA, ICONS, IMAGE_DIMENSIONS
Control_Base_Units	Controls with size + unit	SLIDER, DIMENSIONS
Base_UI_Control	Display-only, no stored data	HEADING, DIVIDER, ALERT, RAW_HTML
Group_Control_Base	Grouped sets of controls	Typography, Background, Border

Available tabs: TAB_CONTENT, TAB_STYLE, TAB_ADVANCED, TAB_RESPONSIVE, TAB_LAYOUT

Common parameters (all controls): label, description, show_label (bool), label_block (bool), separator (default|before|after), condition, conditions, classes, dynamic, global, frontend_available

2. Data Controls Quick Reference

Full PHP code examples for all data controls: see resources/data-controls-examples.md

Text Input Controls

Control	Constant	Returns	Key Params
Text	TEXT	string	input_type, placeholder, title
Textarea	TEXTAREA	string	rows, placeholder
WYSIWYG	WYSIWYG	string	(rich text editor)
Code	CODE	string	language (html|css|javascript), rows
Number	NUMBER	string	min, max, step, placeholder
Hidden	HIDDEN	string	default (only param that matters)

Selection Controls

Control	Constant	Returns	Key Params
Select	SELECT	string	options (key=>label array), groups
Select2	SELECT2	string|array	options, multiple (bool), select2options
Choose	CHOOSE	string	options (key=>[title,icon]), toggle (bool)
Visual Choice	VISUAL_CHOICE	string	options (key=>[title,image])
Switcher	SWITCHER	string	label_on, label_off, return_value (default 'yes')

Unit / Dimension Controls

Control	Constant	Returns	Key Params
Slider	SLIDER	['size'=>int, 'unit'=>string]	size_units, range (per unit: min/max/step)
Dimensions	DIMENSIONS	['top','right','bottom','left','unit','isLinked']	size_units, range, allowed_dimensions
Image Dimensions	IMAGE_DIMENSIONS	['width'=>int, 'height'=>int]	default

Media / Asset Controls

Control	Constant	Returns	Key Params
Color	COLOR	string (hex/rgba)	alpha (bool, default true)
Media	MEDIA	['id'=>int, 'url'=>string]	media_types (default ['image'])
Gallery	GALLERY	array of ['id','url']	default
Icons	ICONS	['value'=>string, 'library'=>string]	default, fa4compatibility, recommended, skin
Icon	ICON	string	DEPRECATED - use ICONS instead
Font	FONT	string	default
URL	URL	['url','is_external','nofollow','custom_attributes']	placeholder, autocomplete, options
Date Time	DATE_TIME	string	picker_options (Flatpickr config)

REPEATER

Returns: array of rows, each row is an assoc array of field values. Use title_field for dynamic row labels.

Render: PHP: $settings['list'] is array of rows. Each row has _id key. Use class elementor-repeater-item-{$item['_id']} for per-item styling with {{CURRENT_ITEM}}. JS template: _.each(settings.list, function(item) { ... item._id ... })

POPOVER_TOGGLE

Used with start_popover() / end_popover() to group controls in a popup.

3. UI Controls

UI controls display information in the panel but store no data.

Control	Constant	Key Params	Purpose
Heading	HEADING	label	Section heading text
Divider	DIVIDER	-	Horizontal separator line
Alert	ALERT	alert_type (info|success|warning|danger), content	Colored alert box
Notice	NOTICE	notice_type, content, dismissible (bool), heading	Dismissible notice
Raw HTML	RAW_HTML	raw, content_classes	Arbitrary HTML in panel
Button	BUTTON	text, button_type (default|success), event	Clickable button
Deprecated Notice	DEPRECATED_NOTICE	widget, since, last, plugin, replacement	Deprecation warning

// HEADING
$this->add_control('heading_style', [
    'label' => esc_html__('Title Style', 'textdomain'),
    'type' => \Elementor\Controls_Manager::HEADING,
    'separator' => 'before',
]);

// DIVIDER
$this->add_control('hr', [
    'type' => \Elementor\Controls_Manager::DIVIDER,
]);

4. Group Controls

Group controls bundle multiple related controls. Use add_group_control() with selector (singular, string) for CSS targeting.

Full PHP code examples for group controls, fields_options, custom controls, and global styles: see resources/group-custom-controls.md

Group Control	Class	Type Getter	Key Params
Typography	Group_Control_Typography	::get_type()	selector, fields_options, global
Background	Group_Control_Background	::get_type()	selector, types (classic|gradient|video|slideshow)
Border	Group_Control_Border	::get_type()	selector, fields_options
Box Shadow	Group_Control_Box_Shadow	::get_type()	selector, exclude
Text Shadow	Group_Control_Text_Shadow	::get_type()	selector, exclude
Text Stroke	Group_Control_Text_Stroke	::get_type()	selector, exclude
CSS Filter	Group_Control_Css_Filter	::get_type()	selector, exclude
Image Size	Group_Control_Image_Size	::get_type()	include, exclude, default

Common group control params: name (required, unique prefix), selector, exclude (array of inner control names), fields_options (override inner control settings).

5. Structural Controls

Sections

Every control must be inside a section. Sections appear as collapsible panels.

$this->start_controls_section('section_id', [
    'label' => esc_html__('Section Name', 'textdomain'),
    'tab' => \Elementor\Controls_Manager::TAB_CONTENT,  // default
    'condition' => [],  // optional
]);
// ... controls ...
$this->end_controls_section();

Tabs (within a section)

Group controls into switchable tabs (e.g., Normal / Hover).

$this->start_controls_tabs('style_tabs');

$this->start_controls_tab('normal_tab', [
    'label' => esc_html__('Normal', 'textdomain'),
]);
// ... normal state controls ...
$this->end_controls_tab();

$this->start_controls_tab('hover_tab', [
    'label' => esc_html__('Hover', 'textdomain'),
]);
// ... hover state controls ...
$this->end_controls_tab();

$this->end_controls_tabs();

Popovers

Group controls in a popup that appears on toggle.

$this->add_control('popover_toggle', [
    'type' => \Elementor\Controls_Manager::POPOVER_TOGGLE,
    'label' => esc_html__('Options', 'textdomain'),
    'label_off' => esc_html__('Default', 'textdomain'),
    'label_on' => esc_html__('Custom', 'textdomain'),
    'return_value' => 'yes',
]);
$this->start_popover();
// ... controls ...
$this->end_popover();

6. CSS Selectors

The {{WRAPPER}} Pattern

All selectors should use {{WRAPPER}} for scoped styling. Resolves to .elementor-{page_id} .elementor-element.elementor-element-{widget_id}.

Value Placeholders by Control Type

Control Type	Selector Pattern
String controls (TEXT, SELECT, COLOR, etc.)	'{{WRAPPER}} .el' => 'property: {{VALUE}};'
SLIDER	'{{WRAPPER}} .el' => 'width: {{SIZE}}{{UNIT}};'
DIMENSIONS	'{{WRAPPER}} .el' => 'margin: {{TOP}}{{UNIT}} {{RIGHT}}{{UNIT}} {{BOTTOM}}{{UNIT}} {{LEFT}}{{UNIT}};'
URL / MEDIA	'{{WRAPPER}} .el' => 'background-image: url({{URL}});'

Multiple Properties in One Selector

'selectors' => [
    '{{WRAPPER}} .el' => 'color: {{VALUE}}; border-color: {{VALUE}}; outline-color: {{VALUE}};',
],

Multiple / Comma-Separated Selectors

'selectors' => [
    '{{WRAPPER}} .heading, {{WRAPPER}} .content' => 'color: {{VALUE}};',
],
// OR as separate keys:
'selectors' => [
    '{{WRAPPER}} .heading' => 'color: {{VALUE}};',
    '{{WRAPPER}} .content' => 'color: {{VALUE}};',
],

RTL/LTR Support

'selectors' => [
    'body:not(.rtl) {{WRAPPER}} .el' => 'padding-left: {{VALUE}};',
    'body.rtl {{WRAPPER}} .el' => 'padding-right: {{VALUE}};',
],

Hover States

// Via group control:
'selector' => '{{WRAPPER}}:hover .el',
// Via tabs: put controls in a "Hover" tab

Cross-Control Values

Reference another control's value by prefixing with the control name:

$this->add_control('aspect_width', [
    'type' => \Elementor\Controls_Manager::NUMBER,
]);
$this->add_control('aspect_height', [
    'type' => \Elementor\Controls_Manager::NUMBER,
    'selectors' => [
        '{{WRAPPER}} img' => 'aspect-ratio: {{aspect_width.VALUE}} / {{aspect_height.VALUE}};',
    ],
]);

Selectors Dictionary

Transform old stored values to new CSS values (backward compat). Only works with string-returning controls.

$this->add_control('align', [
    'type' => \Elementor\Controls_Manager::CHOOSE,
    'selectors_dictionary' => [
        'left' => is_rtl() ? 'end' : 'start',
        'right' => is_rtl() ? 'start' : 'end',
    ],
    'selectors' => [
        '{{WRAPPER}} .el' => 'text-align: {{VALUE}};',
    ],
]);

Element ID

{{ID}} resolves to the element's unique ID. Discouraged -- prefer {{WRAPPER}}.

7. Responsive Controls

Use add_responsive_control() instead of add_control(). Automatically creates per-device controls.

$this->add_responsive_control('spacing', [
    'label' => esc_html__('Spacing', 'textdomain'),
    'type' => \Elementor\Controls_Manager::SLIDER,
    'range' => ['px' => ['min' => 0, 'max' => 100]],
    'devices' => ['desktop', 'tablet', 'mobile'],    // optional, default all 3
    'default' => ['size' => 30, 'unit' => 'px'],
    'tablet_default' => ['size' => 20, 'unit' => 'px'],
    'mobile_default' => ['size' => 10, 'unit' => 'px'],
    'selectors' => [
        '{{WRAPPER}} .el' => 'margin-bottom: {{SIZE}}{{UNIT}};',
    ],
]);

The devices parameter limits which breakpoints appear. Per-device defaults use tablet_default and mobile_default keys. Group controls automatically support responsive for their inner controls.

8. Conditional Display

Basic condition Parameter

// Show only when 'border' switcher is 'yes'
'condition' => ['border' => 'yes'],

// Show when value is one of multiple options (OR)
'condition' => ['type' => ['option1', 'option2']],

// Multiple conditions (AND)
'condition' => [
    'border' => 'yes',
    'border_style!' => '',   // ! suffix = not equal
],

Advanced conditions Parameter

Supports operators: ==, !=, !==, ===, in, !in, contains, !contains, <, <=, >, >=

'conditions' => [
    'relation' => 'or',  // 'and' (default) or 'or'
    'terms' => [
        ['name' => 'type', 'operator' => '===', 'value' => 'video'],
        ['name' => 'type', 'operator' => '===', 'value' => 'slideshow'],
    ],
],

Conditions can be nested. Repeater inner fields can only depend on other inner fields, NOT outer controls.

9. Dynamic Content

Enable dynamic tags (Elementor Pro) on any data control:

$this->add_control('heading', [
    'label' => esc_html__('Heading', 'textdomain'),
    'type' => \Elementor\Controls_Manager::TEXT,
    'dynamic' => ['active' => true],
]);

Works with: TEXT, TEXTAREA, NUMBER, URL, MEDIA, WYSIWYG, and most data controls.

Frontend Available

$this->add_control('slides_count', [
    'type' => \Elementor\Controls_Manager::NUMBER,
    'default' => 3,
    'frontend_available' => true,  // default: false
]);

Access in JS handler: this.getElementSettings('slides_count')

10. Global Styles

Use the global parameter to inherit from the site's design system (set in Site Settings).

Global Colors Constants

• \Elementor\Core\Kits\Documents\Tabs\Global_Colors::COLOR_PRIMARY
• \Elementor\Core\Kits\Documents\Tabs\Global_Colors::COLOR_SECONDARY
• \Elementor\Core\Kits\Documents\Tabs\Global_Colors::COLOR_TEXT
• \Elementor\Core\Kits\Documents\Tabs\Global_Colors::COLOR_ACCENT

Global Typography Constants

• \Elementor\Core\Kits\Documents\Tabs\Global_Typography::TYPOGRAPHY_PRIMARY
• \Elementor\Core\Kits\Documents\Tabs\Global_Typography::TYPOGRAPHY_SECONDARY
• \Elementor\Core\Kits\Documents\Tabs\Global_Typography::TYPOGRAPHY_TEXT
• \Elementor\Core\Kits\Documents\Tabs\Global_Typography::TYPOGRAPHY_ACCENT

Controls with global show a globe icon for users to pick a global style or set custom.

12. Common Mistakes

Mistake	Correct Approach
Using add_control() outside a section	Always wrap in start_controls_section() / end_controls_section()
Using selector (singular) on non-group controls	Non-group controls use selectors (plural, array). Group controls use selector (singular, string).
Forgetting {{WRAPPER}} in selectors	Always prefix selectors with {{WRAPPER}} for scoped styles
Using {{VALUE}} with SLIDER control	SLIDER returns array; use {{SIZE}}{{UNIT}}
Using {{VALUE}} with DIMENSIONS control	Use {{TOP}}{{UNIT}} {{RIGHT}}{{UNIT}} {{BOTTOM}}{{UNIT}} {{LEFT}}{{UNIT}}
Using {{VALUE}} with URL/MEDIA control	Use {{URL}} for the URL component
Nesting start_controls_section inside another	Sections cannot be nested. End one before starting another.
Putting tabs outside a section	start_controls_tabs() must be inside a section
Repeater inner field depending on outer control	Conditional display across repeater levels is not supported
Using selectors_dictionary with array-returning controls	Only works with string-value controls (TEXT, SELECT, CHOOSE, etc.)
Not using esc_html__() for labels	Always internationalize user-facing strings
Setting SWITCHER default to true or 1	SWITCHER returns a string; default should be 'yes' or ''
Using innerHTML = on frontend	Use Elementor's rendering patterns; may be blocked by CSP
Setting REPEATER prevent_empty wrong	Defaults to true; set false if all rows should be deletable