Add Controls to Widgets

Widget controls are added within the _register_controls() method. To add controls to Elementor widgets we need to use the add_control() method.

To add a simple control we have to create a new section. From that point, all the controls will be assigned to that specific section. For new each control we have to define the control name that will be used as the A unique id for that control and an extra set of settings like the control label, control type, etc.

Note that Elementor has a handful list of controls, some are simple controls others are pretty advanced. But each has it’s own set of properties and settings. You should get to know them before using them. In this tutorial we are going to use some of the to learn how to use them in Elementor.

Adding New Control

New controls are added using the add_control() method. Each control has to have a few key parameters:

  • Control Name (string) – Unique name used in the code.
  • Control Setting (array) – Extra control parameters.
    • Label (string) – The label displayed to the user in the panel.
    • Type (string) – The control type.
    • Show Label (bool) – Whether to show the label.
    • Label Block (bool) – Whether to display the label in a separate line.
    • Separator (string) – The position of the separator.

(*) Note that each control has his own set of custom settings.

Adding a new control is done as following:

$this->add_control(
	'control-name',
	[
		'label' => __( 'Control Name', 'plugin-name' ),
		'type' => \Elementor\Controls_Manager::TEXT,
	]
);

Example Controls

Let’s create several controls to understand how it is done an see the result for each one of them.

Text Control

In this example we are going to add a simple text control defined at the Control_Text class which to allow the user to save a simple string, the control will have a placeholder set:

<?php
class Elementor_Test_Widget extends \Elementor\Widget_Base {

	protected function _register_controls() {

		$this->start_controls_section(
			'content_section',
			[
				'label' => __( 'Content', 'plugin-name' ),
			]
		);

		$this->add_control(
			'title',
			[
				'label' => __( 'Title', 'plugin-name' ),
				'type' => \Elementor\Controls_Manager::TEXT,
				'placeholder' => __( 'Enter your title', 'plugin-name' ),
			]
		);

		$this->end_controls_section();

	}

}

Select Control

Another simple example is the Control_Select class which to allow to choose predefined fields:

<?php
class Elementor_Test_Widget extends \Elementor\Widget_Base {

	protected function _register_controls() {

		$this->start_controls_section(
			'content_section',
			[
				'label' => __( 'Content', 'plugin-name' ),
			]
		);

		$this->add_control(
			'open_lightbox',
			[
				'label' => __( 'Lightbox', 'plugin-name' ),
				'type' => \Elementor\Controls_Manager::SELECT,
				'options' => [
					'default' => __( 'Default', 'plugin-name' ),
					'yes' => __( 'Yes', 'plugin-name' ),
					'no' => __( 'No', 'plugin-name' ),
				],
				'default' => 'default',
			]
		);

		$this->end_controls_section();

	}

}

Choose Control

If you liked the select control, you will love the choose control. The Control_Choose class allows the user to choose predefined fields but the components are styled component with an icon for each option.

<?php
class Elementor_Test_Widget extends \Elementor\Widget_Base {

	protected function _register_controls() {

		$this->start_controls_section(
			'content_section',
			[
				'label' => __( 'Content', 'plugin-name' ),
			]
		);

		$this->add_control(
			'alignment',
			[
				'label' => __( 'Alignment', 'plugin-name' ),
				'type' => \Elementor\Controls_Manager::CHOOSE,
				'options' => [
					'left' => [
						'title' => __( 'Left', 'plugin-name' ),
						'icon' => 'fa fa-align-left',
					],
					'center' => [
						'title' => __( 'Center', 'plugin-name' ),
						'icon' => 'fa fa-align-center',
					],
					'right' => [
						'title' => __( 'Right', 'plugin-name' ),
						'icon' => 'fa fa-align-right',
					],
				],
				'default' => 'center',
			]
		);

		$this->end_controls_section();

	}

}

Slider Control

Another useful control is the Control_Slider that displays a draggable range slider:

<?php
class Elementor_Test_Widget extends \Elementor\Widget_Base {

	protected function _register_controls() {

		$this->start_controls_section(
			'content_section',
			[
				'label' => __( 'Content', 'plugin-name' ),
			]
		);

		$this->add_control(
			'font_size',
			[
				'label' => __( 'Size', 'plugin-name' ),
				'type' => \Elementor\Controls_Manager::SLIDER,
				'size_units' => [ 'px', 'em', 'rem' ],
				'range' => [
					'px' => [
						'min' => 1,
						'max' => 200,
					],
				],
				'default' => [
					'unit' => 'px',
					'size' => 20,
				],
			]
		);

		$this->end_controls_section();

	}

}

Color Control

One of the more more popular controls is the Control_Color, it allows to choose a color:

<?php
class Elementor_Test_Widget extends \Elementor\Widget_Base {

	protected function _register_controls() {

		$this->start_controls_section(
			'content_section',
			[
				'label' => __( 'Content', 'plugin-name' ),
			]
		);

		$this->add_control(
			'text_color',
			[
				'label' => __( 'Text Color', 'plugin-name' ),
				'type' => \Elementor\Controls_Manager::COLOR,
				'default' => '#fefefe',
			]
		);

		$this->end_controls_section();

	}

}

Media Control

And finally for advanced uses you can use the Control_Media to select images from the WordPress media library:

<?php
class Elementor_Test_Widget extends \Elementor\Widget_Base {

	protected function _register_controls() {

		$this->start_controls_section(
			'content_section',
			[
				'label' => __( 'Content', 'plugin-name' ),
			]
		);

		$this->add_control(
			'image',
			[
				'label' => __( 'Choose Image', 'plugin-name' ),
				'type' => \Elementor\Controls_Manager::MEDIA,
				'default' => [
					'url' => \Elementor\Utils::get_placeholder_image_src(),
				]
			]
		);

		$this->end_controls_section();

	}

}