Create Atomic Widget

Create atomic widget

Scope: External — the full documented outcome is shippable from a 3rd-party plugin via elementor/widgets/register / elementor/elements/elements_registered; no Elementor Core changes required. Changing the built-in element catalog is Core-only. Full split + disclaimer: skills-scope.md.

Implementation location

• PHP: existing or new third-party plugin repository; plugin-owned namespace/module (e.g. MyPlugin\AtomicWidgets\).
• Do not modify Elementor Core. Built-in elements live in Core at modules/atomic-widgets/elements/ — mirror patterns there only as reference.
• Runnable reference: examples/example-plugin/ (Atomic_Greeting_Widget + Twig). Playground: tests/playwright/blueprints/example-plugin.json.

Prerequisites

• Experiment e_atomic_elements active — see getting-started/experiments.md.
• Often also e_opt_in_v4 on sites still on legacy editor UX.

Read first: atomic-widgets/authoring-widgets.md, hooks.md, rendering.md.

Checklist

1. Pick base class
   • Leaf widget → Atomic_Widget_Base + Has_Template when using Twig.
   • Container → Atomic_Element_Base + Has_Element_Template; set $this->meta( 'is_container', true ) in constructor.
2. Implement required API
   • define_props_schema() — prop types with ->default(); values are PropValue { $$type, value }. Most widgets also declare classes (Classes_Prop_Type) and attributes (Attributes_Prop_Type) — see built-ins under modules/atomic-widgets/elements/.
   • define_atomic_controls() — Section::make()->set_items([ ... ]) with concrete controls from Elementor\Modules\AtomicWidgets\Controls\Types\ (e.g. Text_Control, Select_Control) via ::bind_to( 'key' ). Enum props: pair String_Prop_Type::make()->enum([...])->default(...) with Select_Control::bind_to( 'key' )->set_options([ ['value' => 'h1', 'label' => 'H1'], ... ]) (options are [['value' => ..., 'label' => ...], ...]).
   • Widget (Atomic_Widget_Base): get_element_type() — stable id (e.g. e-my-widget). Container (Atomic_Element_Base): get_element_type() and get_type() (same id); generate() uses get_element_type() on widgets, get_type() on elements.
3. Optional layers
   • Twig: get_templates(), .html.twig files.
   • define_base_styles() → Style_Definition maps.
   • Container: define_allowed_child_types(), define_default_children(), define_default_html_tag().
4. Register
   • Widget: elementor/widgets/register → $manager->register( new My_Widget() ).
   • Element: elementor/elements/elements_registered → $manager->register_element_type( new My_Container() ).
5. Verify
   • Control keys match schema keys exactly.
   • Saved data uses PropValue envelope per prop-value.md.
   • Widget appears under v4-elements panel (Atomic_Widget_Base::get_categories() returns v4-elements by default — custom plugins inherit this; no override needed).
   • get_controls() stays empty (legacy v3 controls unused).

Canonical example (use this, not a shortened skeleton)

Full corrected walkthrough: docs/atomic-builder/examples/create-atomic-widget.md.

Key fixes vs older snippets: base classes under Elements\Base\; primitives under PropTypes\Primitives\; Section::make()->set_items() not add_control().

Test/MCP JSON: My_Widget::generate() or My_Container::generate() — see id methods above.

External implementation path

• Plugin owns PHP classes; register on elementor/widgets/register or elementor/elements/elements_registered.
• Extend schema for all types only via elementor/atomic-widgets/props-schema when type-agnostic — prefer subclassing for type-specific props.
• Filter elementor/atomic-widgets/controls to tweak control trees per element.

Core reference paths (do not edit)

• Built-ins: modules/atomic-widgets/elements/ — see elements-catalog.md.
• Save validation via Props_Parser / Style_Parser; frontend via rendering.md.

See also

• fundamentals/prop-types.md
• extend-prop-types — custom prop types on widget schema
• dynamic-tags/extending.md — dynamic bindings on props