Elementor Builder Reference

Elementor Builder Reference

This page is the technical reference. For what Respira does on Elementor, how it connects to Claude and ChatGPT, and how every edit lands on a copy first, start with the Elementor MCP server page.

Technical documentation for using Respira with Elementor.

Elementor support overview

Respira reads and edits Elementor pages in Elementor's own format: classic widget pages (Elementor v3 widgets, Free and Pro) and pages built with Atomic elements (Elementor v4). Every edit to a published page lands on a draft copy first, with a snapshot to restore from for 90 days. Colours and fonts taken from Site Settings stay linked, and Elementor's own MCP abilities can run through Respira with a snapshot taken first.

What you'll learn:

1. How Respira tells classic widgets and Atomic elements apart, and which Atomic types it writes.
2. Which tools work on Elementor, and what each one is for.
3. How globals, styles written as CSS, and Elementor's own abilities are handled.
4. The safety rules, the limits, and the errors you can meet.

Tip: Ask for native Elementor widgets and elements, not HTML. A page built from real widgets stays editable in the Elementor editor; an HTML widget does not.

About Elementor

Elementor is a drag-and-drop page builder for WordPress. It builds pages from widgets placed in sections, columns and containers, and since Elementor 4 from Atomic elements as well. Elementor Pro adds more widgets and the Theme Builder.

Classic widgets and Atomic elements

Elementor now stores two kinds of element on the same site, and sometimes on the same page:

• Classic widgets (v3). The widgets Elementor had before version 4: heading, text editor, button, image, icon box and the rest, Free and Pro.
• Atomic elements (v4). The newer element set, with types named e-heading, e-paragraph, e-flexbox and so on, styled through classes, variables and per-breakpoint, per-state styles.

When Respira reads a page, it marks each element "kind": "v3-widget" or "kind": "v4-atomic", so the agent writes each one in its own format. respira_list_elementor_widgets reports, for every widget and element, whether it is atomic or classic, whether it can hold children and whether it needs Elementor Pro, read from Elementor itself rather than a fixed list.

Atomic element types Respira writes

Atomic elements are written with per-breakpoint and per-state styles (hover, focus, active and more), and each tree is validated before it is saved.

Prompting for good results on Elementor

For the full prompting guide, see Get Great Results: How to Prompt. Three things matter most on Elementor:

• Ask for native widgets, not HTML. The add tools and respira_build_page write real Elementor widgets and elements. Ask for "HTML" and you get an HTML widget your client cannot edit in the canvas.
• Reuse the design system. Tell the agent to read respira_elementor_design_system first and reuse the kit colours, fonts, v4 variables and global classes already on the site, instead of setting a one-off colour on every element.
• Say which kind of page it is. If a site mixes classic and Atomic pages, name the page and let the agent read it first. It writes each element in the format it already has.

Data structure

Elementor stores page layouts as structured JSON in WordPress post meta (_elementor_data). Each page contains a hierarchical tree of elements. A classic page looks like this:

[
  {
    "id": "abc123",
    "elType": "section",
    "settings": { "layout": "boxed" },
    "elements": [
      {
        "id": "def456",
        "elType": "column",
        "settings": { "width": "50" },
        "elements": [
          {
            "id": "ghi789",
            "elType": "widget",
            "widgetType": "heading",
            "settings": {
              "title": "Welcome",
              "_element_id": "hero-heading"
            }
          }
        ]
      }
    ]
  }
]

Atomic elements live in the same tree. Layout elements carry their own elType (for example e-flexbox), widgets carry a widgetType such as e-heading, and their styles are stored with the element and rendered by Elementor into a separate stylesheet.

Elementor element IDs are seven hex characters, and elements Respira adds get IDs in the same format. After someone has edited a page in the Elementor editor, read the page again and find elements by content or label, not by an ID you read before the editor session.

What a write does

A page write goes through Elementor's own document save where it can, so Elementor's save hooks run. Respira then reads _elementor_data back from the database and refuses to report success when it does not hold what was written. After the save it:

• regenerates the page's Elementor CSS file,
• clears Elementor's element cache and file cache, and on pages with Atomic elements the v4 style cache,
• purges the page in the page caches it recognises: WP Rocket, W3 Total Cache, WP Super Cache, WP Fastest Cache, LiteSpeed Cache, SiteGround Optimizer and the Cloudflare plugin.

Finding an element

Read the page first with respira_get_page_outline or respira_extract_builder_content, then locate the element with respira_find_element. It takes an identifier_type of id, type, admin_label, class, content, text or path, with an identifier_value, and returns a path_string you can pass back to an edit. respira_update_element takes the same pair.

By custom ID or Navigator label (recommended)

Set a CSS ID in Elementor (Widget, Advanced, CSS ID) or name the widget in the Navigator panel. admin_label matches either:

{ "identifier_type": "admin_label", "identifier_value": "hero-heading" }

By element ID

{ "identifier_type": "id", "identifier_value": "a85a3a7" }

By path

Use the path_string that respira_find_element returns. A path names exactly one element:

{ "identifier_type": "path", "identifier_value": "0.2.1" }

By type and content

{ "identifier_type": "type", "identifier_value": "button", "match_content": "Get Started" }

respira_update_module takes the same targets as a module_identifier object, for example { "admin_label": "hero-heading" }, { "path": "0.2.1" } or { "type": "button", "match_content": "Get Started" }.

When an identifier matches more than one element, the edit is refused instead of guessing: respira_update_element and respira_remove_element answer respira_ambiguous_target, and respira_apply_builder_patch answers respira_patch_ambiguous_target for an ID several elements share. Both return the candidate paths, so the agent picks one.

Tools that work on Elementor

Tool names below use the respira_ prefix. The older wordpress_ names still answer, so a saved call keeps working.

Elementor tools

Builder tools that work on Elementor

The add tools were checked by reading the published page after each call: 20 of 22 rendered on Elementor 4.1.1 without Pro. The search box, gallery and pricing table are built from free widgets. The form and slider need Elementor Pro and say so.

Site Settings colours and fonts

On classic widgets, a colour or font taken from Site Settings stays linked. Respira stores the link the way Elementor stores it (in settings.__globals__, for example globals/colors?id=primary), so changing the global in Site Settings updates every element that uses it.

• Writing a new literal colour on a linked control replaces the link, as it does in the Elementor editor.
• respira_update_elementor_global_colors and respira_update_elementor_global_typography change the kit itself, which changes every linked element on the site at once. The change does not wait on a draft copy; Respira snapshots the kit first, so it can be restored.
• On Atomic pages the equivalent is global classes and variables. respira_elementor_design_system returns both, with the reference to write, so the agent reuses them instead of minting a local style per element.

Styles written as CSS

An agent often thinks in CSS. On Atomic elements, a style written as plain CSS goes through Elementor's own converter and lands as Elementor's typed values: padding: 6rem 4rem becomes all four logical sides.

• What the converter cannot take becomes that element's custom CSS.
• What it refuses is named in a warning, not dropped in silence.
• This needs Elementor 4.2 or newer. Older releases keep the value as sent.

Since Elementor 4.2, v4 styles render into their own stylesheet files. Respira rebuilds that stylesheet after every write, so a style shows on the page without someone opening the editor first.

Elementor's own MCP and abilities, through Respira

Elementor 4.3 (22 September 2026) ships Elementor's own MCP, which builds and edits pages made of Atomic elements. Respira does not replace it, and the two can run on the same site.

To call Elementor's abilities through Respira, opt them in under Respira > Abilities, then the agent calls them with respira_invoke_ability. When a call writes to a page, the page is snapshotted first. A change to global classes, variables or default styles is snapshotted as one restore point for the whole design system, and a restore brings back deleted classes under their original IDs.

The full comparison, kept current, is on the Elementor MCP server page. Elementor's own description is on elementor.com/mcp.

Elementor Angie

Angie is Elementor's own AI assistant, a separate free plugin. When Angie is installed, the Respira plugin can register Respira as an MCP server inside Angie, so Angie's chat reaches Respira's tools. Respira does not need Angie, and Angie does not need Respira. See Elementor and Angie.

Safety rules

Respira treats a live Elementor page as something a person approves before it changes.

• Copy first. An edit to a published page lands on a draft copy. A person approves it in WordPress before it goes live, unless the site owner has turned on direct editing.
• Snapshot before every write. Every page write saves the state before it, kept for 90 days by default and restorable with respira_restore_snapshot.
• Two exceptions. The kit tools change Site Settings live (with a kit snapshot first), and respira_elementor_add_custom_js writes to the page ID it is given with no copy and no snapshot.
• No silent overwrite. A write can name the page version it read (expected_version, the content_version every Respira response about a page carries). If the page changed in the meantime the write is refused with respira_version_conflict (409) and nothing is written.
• Untouched elements stay as stored. Since 9.1.6, Atomic nodes a write does not change keep their stored form, including class lists.
• Unsupported types are refused, not dropped. Creating or changing an Atomic type Respira does not model returns respira_elementor_atomic_write_unsupported (422) with the type, the element ID and whether the site's Elementor registers it. Edits to other elements on the same page still work. The same code answers an Atomic tree that fails validation, with the validator's errors.
• Untyped widgets are refused. A write holding a widget with no type is refused with respira_elementor_unresolvable_element_type and nothing is written. The message names the first offending element's path, ID and type.

Recommended operating procedure

1. Read before you write. Start with respira_get_builder_info and respira_get_page_outline, and find the element before you change it.
2. Read the design system. Call respira_elementor_design_system before styling anything.
3. Check the schema. For a widget you have not edited before, call respira_get_elementor_widget_schema.
4. Edit on the copy. Let the edit land on the draft copy, review it in the Elementor editor and on the front end, then approve it.
5. Keep the snapshot. If something looks wrong after approval, restore the snapshot rather than editing by hand.

Limitations

• Atomic types outside the catalog. Types Respira does not model yet are refused with a list of supported types. Edit those in the Elementor canvas for now.
• IDs after an editor session. After someone saves the page in the Elementor editor, read it again and compare by content, not by an ID read earlier.
• Some Pro display conditions. Date ranges and geolocation read fine but cannot be written through the MCP yet.
• Theme Builder templates. Editing Elementor Theme Builder templates (header, footer, single, archive) and their conditions through the MCP is not supported yet. Respira's Theme Builder tools are for Divi.
• Global widgets and saved templates. A widget rendered from a global widget, a saved template or a Theme Builder part lives in its own template post, so it cannot be edited through the page that shows it. Edit the template; the change applies everywhere it is used.
• Dynamic tags, entrance animations, responsive visibility. Respira has no dedicated tool for them. They stay as stored when the element is edited; set them in the Elementor editor.
• Third-party widgets. Support varies by add-on. Their settings appear in respira_get_elementor_widget_schema because the schema is read from Elementor's control registry.

Common errors

Example prompts for Elementor

Content updates:

• "Update the heading widget labeled 'Hero Heading' to say 'Start Here'"
• "Change all button colors on the pricing page to #FF5733"
• "Replace the hero section image with /wp-content/uploads/new-hero.jpg"

Structure queries:

• "Show me all sections on page 42"
• "List all buttons and their text on the homepage"
• "What widgets are in the first section?"

Bulk updates:

• "Find all buttons with 'Learn More' and change text to 'Get Started'"
• "Update all heading widgets to use H2 instead of H3"
• "Change the footer email address across all pages"

Design system:

• "List every colour used on pages built with Elementor that is not linked to a Site Settings global. Group them by value, and suggest which ones should become globals."
• "Which Elementor Pro widgets are actually used on this site, and on how many pages each? Output a markdown table."
• "Find every Elementor button widget whose text is 'Get started' on pages tagged 'campaign'. Change the text to 'Start free' and the URL to /pricing. Show me the diff first."

When to use Respira on Elementor

• Quick content updates. Change headlines, button text or links without opening the builder.
• Bulk edits. Update the same text or link across many pages.
• SEO workflows. Fix heading structure or add missing alt text.
• Design system clean-up. Find one-off colours and fonts and move them to globals.
• Client handoffs. Make content changes after the design is locked, on a copy the client can approve.

New in 9.1: Elementor 4.3 pages

• Pages with an Accordion can be edited again (9.1.6). A page holding an Atomic type outside the catalog refused every write, even to a classic widget, because every write re-sends the whole page. Untouched nodes are now kept as stored, and only changing or creating an unsupported type is refused.
• Untouched v4 elements are left alone (9.1.6). Edits no longer rewrite every Atomic node; written class lists use the shape the running Elementor declares.
• A style added to an element with a class list shows (9.1.6).
• Append works with Elementor's own format (9.1.20). Append mode reads each node on its own, so a new section is converted and saved.
• Headings and paragraphs on Elementor 4.3 (9.1.1). Edits work on pages with the new v4 headings and paragraphs, and a new v4 heading no longer comes out empty.
• Read-only abilities in one switch (9.1.0). Respira > Abilities has a setting, off by default, that lets an agent call any ability its plugin declares read-only and not destructive. On a site with Elementor 4.3 that includes Elementor's page structure and widget schemas. Every call still runs through Respira's activity log and the plugin's own permission check.
• Ability search reads the site (9.1.0). respira_search_abilities searches every ability registered on the site at the moment of the call, Elementor's included.

New in 9.0: Elementor writes checked against Elementor

• Classic Elementor keeps a global a global (9.0.3). A colour or font from the site's globals is stored as a link.
• Undo for Elementor's design system (9.0.4). Global classes, variables and default styles are snapshotted as one restore point before Elementor's own abilities change them.
• The add tools render on Elementor (9.0.4). They store the tool's words where Elementor reads its controls.
• An edit reaches the page (9.0.5). respira_update_element was checked by reading the published page after each call. Added elements get IDs in Elementor's own format, and Elementor 4.2's Loop element is treated as a container.
• A v4 style written as CSS reaches the page (9.0.12). Styles go through Elementor's converter, and the v4 stylesheet is rebuilt after each write.
• v4 widget schemas (9.0.15). respira_get_elementor_widget_schema returns the value shape Elementor accepts for Atomic types such as e-heading, e-button and e-image.

Earlier capabilities

Dynamic schemas (5.2.0 Elemental)

Respira reads the Elementor control registry at runtime and generates JSON Schemas for every widget installed on your site, third-party widgets included, so the agent knows the exact settings, types and valid values.

The schema generator maps Elementor control types to JSON Schema:

• TEXT, TEXTAREA to string
• NUMBER, SLIDER to number (with min and max)
• SELECT, CHOOSE to string (enum)
• COLOR to string (format: color)
• MEDIA to object (url and id)
• REPEATER to array
• GROUP to object (recursive)

Schemas are cached for 12 hours and invalidated when Elementor's version changes.

Validation before save

Before a write is saved, Respira checks the tree. Classic trees are checked for structure (sections hold columns, columns hold widgets). Atomic nodes the write adds or changes are checked against the value formats the running Elementor declares, so something Elementor itself saved cannot block an edit. A widget with no type stops the write.

Element-level operations

Instead of downloading the entire page JSON, an agent can target individual widgets with respira_find_element, respira_update_element, respira_move_element, respira_duplicate_element and respira_remove_element.

HTML to Elementor conversion

respira_convert_html_to_builder (Respira Exhale, the HTML to WordPress converter) turns a finished HTML document into a new Elementor page. It works in two modes:

• fidelity, the default when the document has a stylesheet (plugin 9.0.19 and newer): the document's structure is written as Elementor elements one to one, each class and ID lands on the element Elementor renders, and the stylesheet goes with the page, scoped to it.
• restyle: CSS is mapped to Elementor's own settings: backgrounds, typography, padding and margin, borders and box shadows, and media queries to the tablet and mobile breakpoints.

With preserve_tokens (on by default), colour custom properties declared on :root become Elementor global colours, and the converted content links to them. Colours the site already has are never overwritten. Other tokens, such as sizes, stay as values and are reported as unmapped. For whole HTML files, see Respira Exhale.

7.x

• Elementor v4 (Atomic) writes (7.1.0). respira_update_element, respira_inject_builder_content and respira_build_page write the 9 Atomic widgets and 11 layout elements, with per-breakpoint and per-state styles.
• Digit-leading style IDs render (7.4.11). A style ID that starts with a digit is changed to a valid class that starts with a letter.
• Repeaters can shrink (7.0.64). respira_update_element can remove entries from a repeater, not only add or change them.
• respira_build_page keeps declared children (7.0.64), and reading _elementor_data repairs stray invalid UTF-8.

Support level

Elementor has Full Intelligence support: dynamic schemas, element operations, HTML conversion, validation before save, and the design system tools.

FAQ

Related links

See also

• extract_builder_content: view page structure
• find_element: locate one element
• update_module: update specific widgets
• inject_builder_content: replace or append a whole structure
• get_page_outline: a compact page outline
• Page Builder Overview: compare all supported builders