Atomic Elements (Elementor 4.0+)

Elementor 4.0 introduced an entirely new element system called atomic elements. They use a typed props system (every value wrapped in a $$type object) and a separate styles map for visual styling: fundamentally different shape from legacy widgets.

EMCP Tools adds 18 dedicated tools that only register when ELEMENTOR_VERSION >= 4.0.0: 13 for building atomic elements themselves, plus 5 for reading and authoring the Global Classes design system. Older Elementor versions are unaffected. The legacy widget tools continue to work for everyone.

Detection

emcp-tools/detect-elementor-version

Returns the active Elementor version and whether atomic elements are supported. Call this first before deciding which tool family to use.

Returns: { version: "4.1.2", atomic_supported: true, atomic_tools_available: ["..."] }.

Atomic containers (2)

emcp-tools/add-flexbox

Adds an atomic flexbox container (e-flexbox).

Input:

• post_id, parent_id, position
• direction: row or column
• justify: start, center, end, space-between, etc.
• align: start, center, end, stretch
• gap: number (px)
• wrap: nowrap or wrap
• tag: HTML tag (div, section, article, etc.)
• padding: number or { top, right, bottom, left }
• background_color: hex or globals/colors?id=... reference

emcp-tools/add-div-block

Adds an atomic div-block container (e-div-block). Simpler than flexbox: no flex-specific settings.

Input: post_id, parent_id, position, tag, padding, background_color.

Universal atomic tools (2)

emcp-tools/add-atomic-widget

Adds any atomic widget by type with raw $$type settings. The escape hatch for atomic widgets that don’t have a convenience shortcut yet.

Input:

• post_id, parent_id, position
• widget_type: atomic widget type (e.g. "e-heading", "e-button", custom)
• settings: already-$$type-wrapped settings object
• styles: optional local styles map

emcp-tools/update-atomic-widget

Partial-merge update on an existing atomic widget. Handles $$type wrapping automatically: pass flat values, plugin wraps them.

Input: post_id, element_id, settings (flat: plugin wraps), styles (optional).

Atomic widget shortcuts (8)

All shortcuts take simple flat values; the plugin handles $$type wrapping internally. Each shares these base params: post_id, parent_id, position, css_id.

Tool	Widget	Extra params
add-atomic-heading	e-heading	title, tag (h1-h6), link
add-atomic-paragraph	e-paragraph	content, link
add-atomic-button	e-button	text, link, target_blank
add-atomic-image	e-image	image_id or image_url, alt, link
add-atomic-svg	e-svg	svg_id or svg_url
add-atomic-youtube	e-youtube	video_url
add-atomic-video	e-self-hosted-video	video_url, video_id
add-atomic-divider	e-divider	(no extra)

The data shape (for context)

Atomic elements look fundamentally different from legacy widgets when you read them via get-page-structure:

{
  "id": "abc1234",
  "elType": "widget",
  "widgetType": "e-heading",
  "settings": {
    "tag": { "$$type": "string", "value": "h2" },
    "title": { "$$type": "string", "value": "Welcome" }
  },
  "styles": {
    "abc1234-style-0": {
      "variants": [
        {
          "props": {
            "font-size": { "$$type": "string", "value": "32px" },
            "color": { "$$type": "string", "value": "#111111" }
          }
        }
      ]
    }
  }
}

Key things to know:

• Content props live in settings, each wrapped in { $$type, value }.
• Visual / layout props live in styles[class_id].variants[].props, also $$type-wrapped.
• Style class IDs are auto-generated per element.

The convenience shortcuts hide all of this. The universal add-atomic-widget requires you to pass it pre-wrapped, useful for custom atomic widgets from third-party plugins, harder to get right by hand.

Mixing atomic and legacy

You can have both on the same page. Legacy widgets and atomic elements coexist in the same _elementor_data array. The plugin’s tools route by element type, so add-heading operates on legacy widgets and add-atomic-heading operates on atomic ones. Pick whichever fits the page you’re working with.

For new builds on Elementor 4.0+, atomic is the future. For editing existing pages built with legacy widgets, stick with the legacy tools. Converting wholesale isn’t supported.

Global Classes

Elementor’s Class Manager assigns human-readable names (e.g. card-base) to reusable style classes, but elements only store the opaque g- ID (e.g. g-037bb9c). These tools resolve IDs back to names/CSS, and, new in v3.9.0, let an agent author the design system directly instead of just reading it.

emcp-tools/list-global-classes

Resolves global classes: maps g- IDs back to their label and the CSS properties they define, per breakpoint/state. Read-only (edit_posts).

Input: class_ids — optional array of specific IDs to resolve (e.g. ["g-037bb9c"]). Omit to list every class.

Returns: { count, classes: [{ id, label, css }] }.

emcp-tools/create-global-class

New in v3.9.0. Creates a global class with a label and styles; returns the new g- id to apply to elements. Ships disabled by default.

Input:

• label (required) — human-readable name, e.g. "card-base".
• styles — friendly flat props: background_color, color, width, min_height, border_radius, padding (+ per-side), margin (+ per-side), direction, justify, align, wrap, gap/row_gap/column_gap (each size accepts a matching <key>_unit).
• props — raw escape hatch: CSS property → $$type-wrapped value, for anything styles doesn’t cover. Merged over the built styles.
• breakpoint — one of desktop, widescreen, laptop, tablet_extra, tablet, mobile_extra, mobile. Defaults to desktop.
• state — optional, e.g. hover, focus, active. Omit for the normal state.

emcp-tools/update-global-class

New in v3.9.0. Updates a class by g- id: change its label, and/or merge styles into the variant for a given breakpoint+state (replace_variant: true replaces that variant instead of merging). Ships disabled by default.

Input: id (required), label, styles, props, breakpoint, state, replace_variant (boolean).

Call update-global-class once per breakpoint to build up responsive styles, one variant at a time.

emcp-tools/delete-global-class

New in v3.9.0. Deletes a class by g- id. Ships disabled by default; also requires confirm: true.

Input: id (required), confirm (required, must be true).

Deleting a class affects every element using it

This isn’t just removing an unused definition, it removes the class from every element that has it applied, immediately, with no separate “check usage first” step. Confirm you actually want that before calling it with confirm: true.

emcp-tools/reorder-global-classes

New in v3.9.1. Sets the Class Manager order. That order is the CSS source order, so it decides which class wins when two apply to the same element at equal specificity, this is how you fix a “the wrong class is winning” conflict without touching either class’s styles. Ships disabled by default.

Input: order (required) — the desired top-to-bottom array of g- ids. Classes you omit are appended after, keeping their current relative order, so a partial reorder never drops one.

Enabling the write tools

create-global-class, update-global-class, delete-global-class, and reorder-global-classes are off until you enable them. Open EMCP Tools → Tools, find them under the Elementor category, and toggle the ones you want. Writes are also gated on Elementor’s own elementor_global_classes_update_class capability (falls back to manage_options); a per-tool toggle being on doesn’t bypass that. See Disabling tools.