elementor/add-widget inserts any registered Elementor widget at the root or nested inside a parent element.
The widget type is validated against the live registry before anything is written.
At a glance
| Ability | elementor/add-widget |
| Toolset | Elementor — toolset/elementor |
| Group | Elementor › Elements & Widgets |
| Requires | Elementor, active on the site |
| Capability | manage_options |
| Safety | Writes data |
| 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 |
The registry is per site
Which widgets exist depends on this site: the free set, plus Pro if it is licensed, plus whatever third-party plugins have registered. A widget type that works on one site does not necessarily exist on another.
Writing an unregistered widget type into a document produces an element Elementor cannot render — the editor shows a placeholder, the front end shows nothing, and no error explains it. So the type is checked against the live registry first and an unknown one is refused by name.
The settings keys are the other half of the problem, and they are not guessable. elementor/get-widget-controls returns the controls a widget type actually exposes on this site, which is the call to make before authoring settings.
Settings keys that a widget does not recognise are stored and ignored — no error, no effect — which makes a typo in a control name silent.
Not idempotent.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
post_id | integer | Yes | The post holding the Elementor document. |
widget_type | string | Yes | The registered widget type. |
parent_id | string | null | No | The element to insert into. Null or omitted inserts at the document root. |
position | integer | No | Index among the parent’s children. Omitted appends at the end. |
settings | object | No | Widget settings, keyed as the widget’s own controls expect. |
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:
Add a testimonial widget to that container.
It resolves to one call:
{
"ability": "elementor/add-widget",
"parameters": {
"post_id": 412,
"widget_type": "testimonial",
"parent_id": "a1b2c3d"
}
}Worth knowing
- The registry is site-specific. An unknown type is refused by name.
- Unrecognised settings keys are stored and ignored, silently.
- Read the widget’s controls before authoring settings.
- Not idempotent.
Related abilities
- Get Elementor Widget Controls — discover the settings keys
- Get Elementor Official Widget Catalog — what exists in principle
- Add Elementor Container — somewhere to put it
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category