elementor-controls（元素控制）

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:

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

Selection Controls

Unit / Dimension Controls

Media / Asset Controls

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.

// 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

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

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