Widgets

As of v3.0.0 the 62 per-widget convenience tools and the old universal add-widget were replaced by a catalog-backed model. Instead of one tool per widget, the 62 curated widgets’ tiers, categories, and curated params live as data in a built-in catalog (now 29 free, including the two EMCP Themer loop widgets, 30 Pro and 5 WooCommerce), served by five tools. This cut the per-turn widget tool-list cost ~10× (≈18–20k → ≈2k tokens) with no loss of capability: every widget and every curated parameter is still reachable, and any valid Elementor control passes straight through.

The flow is discover → inspect → act.

The widget tools register while Elementor is the builder selected on EMCP Tools → Page Builders. add-free-widget and update-widget are in the Widgets section of the Elementor tab on EMCP Tools → Tools; list-widgets and get-widget-schema are in the Query & Discovery section of the same tab.

1. Discover: emcp-tools/list-widgets

Returns a compact catalog index. Filter to narrow it down.

Input:

• tier: free, pro, or woo
• category: e.g. basic, general, media, form, woocommerce, themer
• search: matches intent across title, use case and keywords

Returns: { widgets: [{ type, title, tier, category, use_case, param_names, requires }] }.

2. Inspect: emcp-tools/get-widget-schema

Returns the curated params for a widget by default: the handful of settings you actually need, with types and defaults. Pass full: true for the raw auto-generated control schema.

Input:

• widget_type: a single widget type, or
• types: an array of widget types (batch inspect, returns { widgets: [...] })
• full: true to return the complete control schema instead of curated params

Returns: { widget_type, tier, use_case, params, required, defaults } (or { schema } when full: true).

3. Act

emcp-tools/add-free-widget

Adds any free/core widget by type. Catalog defaults for that widget are merged in automatically. Always registered. (Folds in the old add-widget.)

Input: post_id, parent_id (container), widget_type, settings (optional, merged over catalog defaults), position (default -1 to append), dynamic (optional; bind a field to a live data source instead of a static value: { <field_name>: { source, args? } }, source is an EMCP Themer source key. Not re-validated for type match at call time on this Elementor path, so pass a source the target field can actually use).

Returns: { element_id }.

emcp-tools/add-pro-widget

Adds an Elementor Pro or WooCommerce widget by type. Registered only when Elementor Pro is active. WooCommerce widgets are reached here too (catalog tier woo). They add no separate tools. It is switched on by default. You can turn it off in the Widgets section of the Elementor tab, then choose Save changes in the save bar.

Input: same shape as add-free-widget.

Returns: { element_id }.

emcp-tools/update-widget

Updates settings on an existing widget (partial-merge, same semantics as update-element).

Input: post_id, element_id, settings. Does not accept dynamic: set a binding when you create the widget with add-free-widget/add-pro-widget.

What’s in the catalog

The catalog is the data behind list-widgets. You reach every entry through add-free-widget / add-pro-widget. The curated set:

Free (29): heading, text-editor, image, button, video, icon, spacer, divider, icon-box, accordion, alert, counter, google_maps, icon-list, image-box, image-carousel, progress, social-icons, star-rating, tabs, testimonial, toggle, html, menu-anchor, shortcode, rating, text-path, plus emcp-loop-grid and emcp-loop-carousel (new in 3.18.0, category themer). The two loop widgets repeat an EMCP Themer Loop Item and need the EMCP Themer module; see EMCP Themer.

Pro (30): form, posts, countdown, price-table, flip-box, animated-headline, call-to-action, slides, testimonial-carousel, price-list, gallery, share-buttons, table-of-contents, blockquote, lottie, hotspot, nav-menu, loop-grid, loop-carousel, media-carousel, nested-tabs, nested-accordion, portfolio, author-box, login, code-highlight, reviews, off-canvas, progress-tracker, search.

WooCommerce (5, requires WC + Pro): woocommerce-products, wc-add-to-cart, woocommerce-cart, woocommerce-checkout-page, woocommerce-menu-cart.

The catalog is curated for ergonomics, not a hard limit: add-free-widget / add-pro-widget accept any registered widget type, including custom or third-party widgets. Use get-widget-schema with full: true to discover their controls.

Typical sequence

list-widgets { "category": "form" }       → find the "form" Pro widget
get-widget-schema { "widget_type": "form" } → see curated params
add-pro-widget { post_id, parent_id, widget_type: "form", settings: {…} }
update-widget  { post_id, element_id, settings: {…} }   → tweak later