elementor/update-element replaces the element at a given ID with a new element payload.
It is guarded by force_replace because replacement takes the children with it.
Before you run it
This replaces the element and every child it has. A container with twenty widgets inside it, replaced with an empty container, loses all twenty — and the payload that does it looks perfectly reasonable. force_replace is the guard, and elementor/merge-element-settings is what you almost always want instead.
At a glance
| Ability | elementor/update-element |
| Toolset | Elementor — toolset/elementor |
| Group | Elementor › Elements & Widgets |
| Requires | Elementor, active on the site |
| Capability | manage_options |
| Safety | Destructive — replaces an element and everything inside it. Guarded by force_replace rather than a confirmation flag. |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
How it works
Replacement is occasionally the right operation — changing a widget’s type, rebuilding a subtree from a known-good structure, applying a payload produced elsewhere.
Far more often the intent is to change a setting, and replacement is a very expensive way to do that. elementor/merge-element-settings exists for the common case.
The guard fires when the replacement would remove content: a populated element being replaced by something smaller. That is the shape of the accident, and requiring an explicit flag makes it deliberate.
The element ID is preserved through the replacement, so anything referencing it — a link anchor, a CSS selector in custom code — keeps working.
Not idempotent in general, since the payload may contain child elements whose IDs are regenerated.
Elementor generates a CSS file per post and caches it. A change to the document does not change the rendered page until that CSS is regenerated, which is why elementor/clear-cache is the second half of several operations here.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
post_id | integer | Yes | The post holding the Elementor document. |
element_id | string | Yes | The seven-character hex element ID. |
element | object | Yes | The replacement element payload. |
force_replace | boolean | When replacing populated content | Required when the replacement would remove existing children. |
What comes back
| Name | Type | What it is |
|---|---|---|
post_id | integer | The post written. |
element_id | string | The ID of the element created or affected. |
element | object | The element as stored. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Replace that widget with a different one.
It resolves to one call:
{
"ability": "elementor/update-element",
"parameters": {
"post_id": 412,
"element_id": "a1b2c3d",
"element": { "elType": "widget", "widgetType": "heading", "settings": { "title": "New" } },
"force_replace": true
}
}Worth knowing
- Replacement removes every child. The guard exists for exactly that.
- Use the merge ability for ordinary setting changes.
- The element ID survives the replacement.
- Clear the Elementor cache afterwards.
Related abilities
- Merge Elementor Element Settings — the safe alternative
- Get Elementor Element — read what you are about to replace
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category