| 1 |
Create and manage Elementor components — user-facing reusable compositions of widgets, placed elsewhere via `<e-component>` in `elementor/build-composition` (see `elementor/list-components`). |
| 2 |
|
| 3 |
Requires administrator access. `create`, `rename`, and `archive` additionally require an active Elementor Pro license; `publish` and `update` also work with an expired license. Without the required license, calls fail with `insufficient_permissions`. |
| 4 |
|
| 5 |
# COMPONENT INTENT |
| 6 |
An Elementor component is a persistent, reusable widget composition. It is not a global CSS class and is not merely a group of raw widgets placed on one page. |
| 7 |
|
| 8 |
Treat "create/build components", "with components", "basic components", and "component library/design system" as requests to create missing Elementor components. When a request separately names variables, classes, and components, all three are distinct deliverables. |
| 9 |
|
| 10 |
Before creating a component, call `elementor/list-components` and reuse a matching component when its exposed properties cover the requested customization. If component creation fails, report the failure instead of substituting a global class and claiming that it is a component. |
| 11 |
|
| 12 |
# ACTIONS |
| 13 |
Every call takes one `action`: `create`, `update`, `rename`, `archive`, `publish`. |
| 14 |
|
| 15 |
## create |
| 16 |
Requires `title` (2-200 chars). Choose ONE source for the initial content, or omit both to create an empty component: |
| 17 |
- **xml_structure**: same tag language as `elementor/build-composition` (`element_config`, `classes`, `style`, `interactions`). It must contain exactly one root element, and every element needs a unique `configuration-id`. |
| 18 |
- **source_post_id** + **element_id**: copy an existing element (and its children) from another document — get `element_id` from `elementor/get-page-structure`. All ids are regenerated on the copy. |
| 19 |
|
| 20 |
Optionally attach `overridable_props` (see below). Returns `component_id`, `uid`, `edit_url`. |
| 21 |
|
| 22 |
`xml_structure` may contain self-closing `<e-component configuration-id="…"/>` nodes to instance other components (leaf tag; no children inside `<e-component>`). `configuration-id` identifies the instance within the request; configure the reusable component it references via `element_config` using the flat `{ component_id, overrides? }` shape documented in `build-composition.md` COMPONENTS section. |
| 23 |
|
| 24 |
```json |
| 25 |
{ |
| 26 |
"action": "create", |
| 27 |
"title": "Two Cards", |
| 28 |
"xml_structure": "<e-flexbox configuration-id=\"row\"><e-component configuration-id=\"card-a\"/><e-component configuration-id=\"card-b\"/></e-flexbox>", |
| 29 |
"element_config": { |
| 30 |
"card-a": { "component_id": 42, "overrides": { "title": "First Card", "image": { "src": { "url": "https://example.com/a.jpg" }, "size": "full" } } }, |
| 31 |
"card-b": { "component_id": 42, "overrides": { "title": "Second Card", "image": { "src": { "url": "https://example.com/b.jpg" }, "size": "full" } } } |
| 32 |
} |
| 33 |
} |
| 34 |
``` |
| 35 |
|
| 36 |
Prefer instancing an existing component over inlining its widgets. If a matching component exists (check via `elementor/list-components`), place `<e-component>` instead of duplicating the subtree. |
| 37 |
## update |
| 38 |
Requires `component_id`. Two modes: |
| 39 |
- **With `xml_structure`**: replaces the ENTIRE component tree (same params as `create`'s xml_structure path). Not a merge — re-send the full composition. |
| 40 |
- **Without `xml_structure`**: requires `overridable_props`; only overridable-props metadata changes, the element tree is untouched. |
| 41 |
|
| 42 |
## rename |
| 43 |
Requires `component_id` and `title` (2-200 chars). |
| 44 |
|
| 45 |
## archive |
| 46 |
Requires `component_ids` (array). Archived components stop being listed by `elementor/list-components` and can no longer be placed in compositions. Returns `success_ids` / `failed_ids` per id. |
| 47 |
|
| 48 |
## publish |
| 49 |
Requires `component_id`. Promotes a pending draft/autosave (created via `publish_status: "draft"`) to the live version. |
| 50 |
|
| 51 |
# publish_status |
| 52 |
Applies to `create`, `update`, `rename`, `archive`. Defaults to `"publish"` (operates on the live document immediately). Pass `"draft"` to stage changes in an autosave that does NOT affect pages already using this component until you call `action: "publish"`. |
| 53 |
|
| 54 |
# overridable_props |
| 55 |
Exposes per-instance customization points, surfaced later via `elementor/list-components`' `overridable_props` and set via `<e-component>` `element_config.overrides` in `elementor/build-composition`. |
| 56 |
|
| 57 |
Record mapping a caller-chosen override key → `{ target, prop_key, label, group? }`: |
| 58 |
- `target`: which element to expose a prop from. |
| 59 |
- With `xml_structure` (create or update): the `configuration-id` you set on that element. |
| 60 |
- With `source_post_id`/`element_id` (create), or `update` without `xml_structure`: the real element id (from `elementor/get-page-structure`). |
| 61 |
- `prop_key`: identifies WHICH setting to expose. Meaning depends on the target: |
| 62 |
- Raw widget / atomic element (`<e-heading>`, `<e-image>`, `<e-flexbox>`, etc.): the setting name on that element (from `elementor/get-widget-schema`). |
| 63 |
- Nested `<e-component>` instance (expose-further): the inner component's own exposed override key (from `elementor/list-components` `overridable_props` for that component). The inner component must already expose the prop before you can re-expose it through the wrapper. |
| 64 |
- `label`: human-readable name shown to whoever configures an instance. |
| 65 |
- `group` (optional): label used to group related overrides together; defaults to "Default". |
| 66 |
|
| 67 |
The current/default value of `prop_key` becomes the override's origin value automatically — do NOT try to set it yourself. |
| 68 |
|
| 69 |
Expose-further composes through any depth: if the inner component's exposed key was itself exposed from a grand-child, the wrapper's control still resolves to the underlying raw widget's schema. |
| 70 |
|
| 71 |
Example — a `Cards Grid` wrapper that re-exposes `caption`/`image` from each nested `<e-component>` instance of a `Card` component (which itself exposes `caption` from an `<e-paragraph>` and `image` from an `<e-image>`): |
| 72 |
|
| 73 |
```json |
| 74 |
{ |
| 75 |
"action": "create", |
| 76 |
"title": "Cards Grid", |
| 77 |
"xml_structure": "<e-flexbox configuration-id=\"grid\"><e-component configuration-id=\"card-1\"/><e-component configuration-id=\"card-2\"/></e-flexbox>", |
| 78 |
"element_config": { |
| 79 |
"card-1": { "component_id": 42 }, |
| 80 |
"card-2": { "component_id": 42 } |
| 81 |
}, |
| 82 |
"overridable_props": { |
| 83 |
"card_1_caption": { "target": "card-1", "prop_key": "caption", "label": "Card 1 Caption", "group": "Card 1" }, |
| 84 |
"card_1_image": { "target": "card-1", "prop_key": "image", "label": "Card 1 Image", "group": "Card 1" }, |
| 85 |
"card_2_caption": { "target": "card-2", "prop_key": "caption", "label": "Card 2 Caption", "group": "Card 2" }, |
| 86 |
"card_2_image": { "target": "card-2", "prop_key": "image", "label": "Card 2 Image", "group": "Card 2" } |
| 87 |
} |
| 88 |
} |
| 89 |
``` |
| 90 |
|
| 91 |
```json |
| 92 |
{ |
| 93 |
"action": "create", |
| 94 |
"title": "Hero Section", |
| 95 |
"xml_structure": "<e-flexbox configuration-id=\"hero\"><e-heading configuration-id=\"hero-title\"></e-heading></e-flexbox>", |
| 96 |
"element_config": { |
| 97 |
"hero-title": { "title": "Welcome" } |
| 98 |
}, |
| 99 |
"overridable_props": { |
| 100 |
"heading-text": { |
| 101 |
"target": "hero-title", |
| 102 |
"prop_key": "title", |
| 103 |
"label": "Heading Text" |
| 104 |
} |
| 105 |
} |
| 106 |
} |
| 107 |
``` |
| 108 |
|
| 109 |
# FURTHER INSTRUCTIONS |
| 110 |
Every successful response includes `edit_url` and `llm_instructions` — components have no public permalink, so you MUST share `edit_url` with the user to review the change. |
| 111 |
|
