{"slug":"elementor-v3-widget-development","title":"elementor-v3-widget-development","summary":"Builds and reviews production-ready classic Elementor widgets based on `Elementor\\Widget_Base`: companion-plugin bootstrap and compatibility gates, `elementor/widgets/register`, widget identity, PHP and editor rendering, render attributes, asset dependencies, frontend handlers, a","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-16T14:51:43.564705Z","repo":{"url":"https://github.com/Lonsdale201/wp-agent-skills","stars":22,"forks":2,"license":"MIT","updatedAt":"2026-09-26T23:03:36Z"},"bodyHtml":"
\n

name: elementor-v3-widget-development\ndescription: >-\nBuilds and reviews production-ready classic Elementor widgets based on\nElementor\\Widget_Base: companion-plugin bootstrap and compatibility gates,\nelementor/widgets/register, widget identity, PHP and editor rendering,\nrender attributes, asset dependencies, frontend handlers, accessibility,\noutput caching, and regression tests. Use when code extends Widget_Base,\nimplements register_controls() or render(), registers an Elementor\nwidget/category, or must distinguish the established V3 widget API from\nAtomic Widgets / Editor V4. Does not cover custom control types.\nmetadata:\nwp-skills-author: \"Soczó Kristóf\"\nwp-skills-contact: \"mailto:lonsdale201@hotmail.com\"\nwp-skills-plugin: \"elementor\"\nwp-skills-plugin-version-tested: \"4.2.3 (free) / 4.2.2 (pro)\"\nwp-skills-wp-version-tested: \"7.1\"\nwp-skills-php-min: \"7.4\"\nwp-skills-api-stable-since: \"3.5.0\"\nwp-skills-last-updated: \"2026-08-22\"

\n

Elementor V3 widget development

\n

Build companion-plugin widgets on Elementor's established Widget_Base / Controls_Stack architecture. Treat V3 here as the classic editor/widget model, not as an installed Elementor 3.x version: this API remains available and is used by core widgets in Elementor 4.2.3.

\n

Do not mix this model with Atomic Widgets / Editor V4. Atomic widgets extend classes under Elementor\\Modules\\AtomicWidgets, declare prop types and styles differently, and remain a moving surface. Never translate a V3 control array into an Atomic schema by guesswork.

\n

When to use this skill

\n\n

For a complete companion-plugin skeleton and test matrix, read references/widget-contract-and-example.md. Load elementor-v3-widget-controls as well when designing or reviewing the control schema.

\n

Architecture boundary

\n

Use the following identity test before editing:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ModelBase/signalsThis skill
Classic V3 widgetElementor\\Widget_Base, Controls_Manager, register_controls(), render()In scope
Atomic / Editor V4Modules\\AtomicWidgets, Atomic_Widget_Base, prop types, Atomic controls/stylesOut of scope
Elementor plugin versionELEMENTOR_VERSION, currently 4.2.3 in the tested installIndependent of the model name
\n

Allow both models to coexist in a plugin only behind separate classes and registration paths. Do not make Atomic feature flags a prerequisite for a classic widget.

\n

Workflow

\n

1. Gate the companion plugin before loading widget classes

\n
    \n
  1. Declare Requires Plugins: elementor in the plugin header on supported WordPress versions.
    2. \n
  2. Run compatibility checks after plugins load. Verify did_action( 'elementor/loaded' ), ELEMENTOR_VERSION, and the addon's actual PHP minimum.
    3. \n
  3. Do not include a file that extends Widget_Base until Elementor is loaded; otherwise a missing/inactive Elementor causes a fatal before a notice can run.
    4. \n
  4. Register callbacks only when requirements pass. Keep Pro optional unless the widget genuinely extends a Pro-only API.
    5. \n
\n

Choose and document a real minimum Elementor version. The modern widget registration contract used here is stable since 3.5.0; a tested-up-to value is not a minimum-version claim.

\n

2. Register, do not instantiate early

\n

Hook the manager and pass a widget instance:

\n
add_action(\n    'elementor/widgets/register',\n    static function ( \\Elementor\\Widgets_Manager $widgets_manager ): void {\n        require_once __DIR__ . '/includes/class-example-widget.php';\n        $widgets_manager->register( new Example_Widget() );\n    }\n);\n
\n\n

3. Implement the smallest correct widget contract

\n

Implement these methods deliberately:

\n
public function get_name(): string;\npublic function get_title(): string;\npublic function get_icon(): string;\npublic function get_categories(): array;\npublic function get_keywords(): array;\nprotected function register_controls(): void;\nprotected function render(): void;\n
\n

get_icon(), categories, and keywords have base defaults, but explicit metadata makes a public widget discoverable and predictable. Translate human-facing strings; do not translate identifiers, control IDs, script handles, or category slugs.

\n

Use register_controls(), never deprecated _register_controls(). Delegate the control array and value-shape work to elementor-v3-widget-controls.

\n

4. Make PHP rendering canonical and safe

\n
    \n
  1. Read display values with $this->get_settings_for_display(). It applies active-control conditions and dynamic-tag parsing; get_settings() is raw saved/default data. Process shortcodes only through an explicit renderer such as parse_text_editor() or do_shortcode() when the widget intentionally supports them.
    2. \n
  2. Validate enumerations again at output time. Saved Elementor JSON, REST/import operations, filters, and dynamic tags can bypass the editor's option list.
    3. \n
  3. Escape at the final output context: esc_html(), wp_kses_post(), esc_url(), or an explicit wp_kses() allowlist. Control registration is not an output sanitizer.
    4. \n
  4. Build attributes through add_render_attribute() and print_render_attribute_string(). Build URL-control links through add_link_attributes().
    5. \n
  5. Use add_inline_editing_attributes() only on text nodes intended for editor editing. For repeaters, derive a unique key with get_repeater_setting_key().
    6. \n
  6. Return early for empty optional content rather than emitting empty semantic elements.
    7. \n
  7. Emit valid semantic HTML and accessible names/states. Do not use a clickable div where a button or link is required.
    8. \n
\n

Treat render() as the source of truth. Add content_template() only when immediate Backbone-based editor preview is worth maintaining, then keep its structure, conditions, attributes, and escaping intent in parity with PHP. Never move authorization or sensitive lookup logic into the JS template.

\n

Override render_plain_content() when the default rendered HTML is unsuitable for WordPress search, SEO extraction, feeds, or Elementor deactivation. Return meaningful plain content, a shortcode when appropriate, or an empty string for functionality that must not survive deactivation.

\n

5. Register assets once and declare dependencies

\n

Register handles on a WordPress enqueue hook; do not enqueue globally and do not register them on every render() call:

\n
add_action( 'wp_enqueue_scripts', static function (): void {\n    wp_register_style( 'acme-example-widget', plugins_url( 'assets/widget.css', __FILE__ ), [], '1.0.0' );\n    wp_register_script( 'acme-example-widget', plugins_url( 'assets/widget.js', __FILE__ ), [ 'elementor-frontend' ], '1.0.0', true );\n} );\n
\n

Return registered handles from get_style_depends() / get_script_depends(). Elementor then loads them for pages containing the widget, including the preview iframe. Use elementor/editor/before_enqueue_scripts or .../after_enqueue_scripts only for code that belongs to the editor panel itself.

\n

For interactive widgets, initialize each instance from:

\n
jQuery( window ).on( 'elementor/frontend/init', () => {\n    elementorFrontend.hooks.addAction(\n        'frontend/element_ready/acme-example.default',\n        ( $scope ) => { /* initialize only inside $scope */ }\n    );\n} );\n
\n\n

6. Decide output caching from runtime behavior

\n

The base returns true from is_dynamic_content(), so output is not declared cacheable. Override it to false only when output is stable for all users/requests and fully determined by cache-safe settings/dependencies:

\n
protected function is_dynamic_content(): bool {\n    return false;\n}\n
\n

Keep the default true when rendering depends on the current user, cookies/session, request, time, randomness, stock/entitlement state, uncached remote data, or mutable external state. Elementor separately detects configured dynamic tags, but that does not prove arbitrary PHP logic is static.

\n

For inner-wrapper compatibility and icon rendering, apply elementor-experiments-and-markup. Do not assume .elementor-widget-container exists on core widgets, and render ICONS values through Icons_Manager::render_icon().

\n

Critical rules

\n\n

Review checks

\n\n

Cross-references

\n\n

What this skill does NOT cover

\n\n

References

\n\n","files":[{"path":"agents/openai.yaml","sizeBytes":250,"isText":true},{"path":"references/widget-contract-and-example.md","sizeBytes":15561,"isText":true},{"path":"SKILL.md","sizeBytes":12728,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-16T14:55:17.93738Z","sha256":"FB2E1674E947C546A297323EA88BD06E2B27C20A27CCF94E198E9E477407165C","sizeBytes":10535},"review":null,"source":{"repositoryUrl":"https://github.com/Lonsdale201/wp-agent-skills","path":"elementor/elementor-v3-widget-development","license":"MIT","commit":"c51b571a259f0c4b5f5c0a3bc50ed580c6851f98","subtreeSha":"954651120286E2D98E775AEF39D15E4F77DF52151D90B5B832294B54C7CF4770","lastSyncedAt":"2026-09-29T23:33:03.303675Z"},"reviewedAt":"2026-09-16T15:10:08.689261Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/Lonsdale201/wp-agent-skills/tree/main/elementor/elementor-v3-widget-development"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install lonsdale201-wp-agent-skills@llmmart"},{"target":"git","command":"git clone https://github.com/Lonsdale201/wp-agent-skills.git"}]}