WordPress & Elementor Pro — Skill Router

A complete procedural guide for producing production-grade WordPress and Elementor Pro code. This file is the router — read it first, then load the relevant sub-file(s) for the task at hand.

Sub-file Map — Read the Right File for Each Task

| Task type | Read this file | |---|---| | Plugin scaffold, child theme, code placement, CPT, AJAX handler | scaffolding.md | | PHP standards, sanitization, escaping, nonces, WP_Error, transients, password hashing | php-standards.md | | JavaScript standards, enqueue API, defer/async, wp_add_inline_script | js-css-standards.md | | CSS standards, BEM, design tokens, Elementor CSS selectors | js-css-standards.md | | Elementor custom widget, Dynamic Tags, Loop Grid, Form actions, Theme Builder conditions | elementor-patterns.md | | Elementor extension points — custom form fields, theme locations, injecting controls into native widgets, adding a TAB to the editor's Elements panel, Finder/context-menu, hooks reference, deprecations | elementor-extending.md | | WooCommerce HPOS, order API, template overrides, Loop Grid for products | woocommerce.md | | REST API endpoints, schema, permission callbacks | rest-api.md | | Off-canvas UI, off-canvas accessibility, focus trap | offcanvas-ui.md | | Performance checklists (frontend + backend), speculative loading, IE conditional comments | performance.md | | Accessibility checklist, WCAG 2.2 AA, ARIA patterns | performance.md | | Hard-won production gotchas — widget lifecycle fatals, content_template() escaping, CSS-in-Elementor footguns, transactional email, wp.org review/packaging, embedding apps, AJAX/loop re-rendering, dynamic CSS in loops, Swiper on optimised sites, holding a login without counting it as failed | field-notes.md | | wordpress.org submission — the 18 Directory Guidelines, Plugin Check 2.1.0 categories/usage, review process, required headers/readme | wp-org-guidelines.md | | Subversion (SVN) — deploying/tagging a release on the wordpress.org plugin/theme SVN (trunk/tags/assets), the daily work cycle, branching/merging, properties, repo admin | svn/svn.md (self-contained sub-bundle; svn/references/ goes deeper) | | Debugging & static analysis — PHPCS+WPCS, PHPStan, Plugin Check, WP_DEBUG/Query Monitor, Elementor Safe Mode/cache, symptom→cause table | debugging.md | | Common WordPress APIs — admin settings page (Settings + Options API), register_meta, roles/capabilities, WP-Cron, internationalization (i18n) | wordpress-apis.md | | Database layer (MariaDB/MySQL) — custom tables + dbDelta(), charsets & the varchar(191) index rule, indexes, EXPLAIN, MariaDB↔MySQL portability, sql_mode, full-text | mariadb.md |

Widget Boilerplates — Load when building a widget of that type

| Widget type | Read this file | |---|---| | Button / CTA with icon and link | widget-button.md | | Container / layout wrapper / section / card shell | widget-container.md | | Image with caption, link, lightbox | widget-image.md | | Heading / title / HTML tag selector | widget-heading.md | | Rich text / WYSIWYG body content | widget-text-editor.md | | Video embed (YouTube, Vimeo, self-hosted) | widget-video.md | | Widget that renders a saved Elementor template by ID | widget-elementor-template.md (SELECT2, get_builder_content_for_display(), Dynamic Tags context, CSS timing) | | Widget whose markup lives in a separate PHP template file | widget-php-template.md (Strategies A/B/C, load_template(), ob_start, path-traversal safety) | | Divider / horizontal rule with optional text or icon | widget-divider.md | | Spacer / vertical gap | widget-spacer.md | | Single standalone icon with optional link | widget-icon.md | | Icon + title + description box | widget-icon-box.md | | Image + title + description box | widget-image-box.md | | Image grid / gallery | widget-image-gallery.md | | Image slider / carousel | widget-image-carousel.md | | Bullet list with icons per item | widget-icon-list.md | | Animated number counter | widget-counter.md | | Percentage progress bar | widget-progress.md | | Customer quote / testimonial | widget-testimonial.md | | Tabbed content panels | widget-tabs.md | | Accordion — one panel open at a time | widget-accordion.md | | Toggle — multiple panels open simultaneously | widget-toggle.md | | Social media icon links row | widget-social-icons.md | | Colored alert / notice box | widget-alert.md | | Audio player (SoundCloud / self-hosted) | widget-audio.md | | WordPress shortcode output | widget-shortcode.md | | Raw custom HTML / JS / CSS embed | widget-html.md | | Named anchor for in-page navigation | widget-menu-anchor.md | | WordPress registered sidebar output | widget-sidebar.md | | WordPress  read more tag | widget-read-more.md | | Google Maps embed | widget-google-maps.md | | Decorative star rating display | widget-star-rating.md | | Schema-ready structured rating | widget-rating.md | | Text following a curved / custom SVG path | widget-text-path.md | | Nested Tabs / Nested Accordion (each panel is a Container holding any widgets) | widget-nested.md |

Always read the relevant sub-file before writing code. For tasks that span multiple areas (e.g. a WooCommerce widget with custom REST endpoint), read all relevant sub-files. For a widget task, read BOTH the widget boilerplate file AND elementor-patterns.md. For any custom widget, plugin, or wp.org-bound work, also skim field-notes.md — it catches the lint-passing, review-failing, site-down mistakes the topic files don't dwell on.

0. Golden Rules (Never Violate)

These override everything in all sub-files:

Native APIs first — WordPress core hook before plugin; Elementor API before template override.
Sanitize in, escape out — Every input sanitized. Every output escaped. No exceptions.
Prefix everything — All functions, classes, constants, hooks, and CSS classes use a project-specific prefix.
State your placement — Every code response must declare exactly where the code lives.
No over-clarifying — Only ask a clarification question if the missing info would materially change the code output. Otherwise, state your assumption and proceed.
NEVER hardcode visual settings in widgets — Every visual property (colors, fonts, sizes, spacing, backgrounds, borders, shadows, alignment) MUST be exposed as a standard Elementor control in the editor panel. Users control appearance via the toolbar — not by editing code. See §5 "Mandatory Widget Controls" below for the required controls checklist.
Name for the directory from day one — Naming is decided first and is effectively irreversible, so get it right before writing code. The plugin slug/name must NOT start with a trademark you don't own — "CRM for WooCommerce", never "WooCommerce CRM" (Directory Guideline 17). The text domain must exactly equal the plugin slug. The wp.org slug is permanent, and a widget's get_name() is sticky (stored in every page's _elementor_data — renaming it breaks placed widgets). Choose the public name, slug, text domain, and code prefix (Rule #3) together, once. This is distinct from Rule #3: that governs internal code symbols; this governs the public identity. See wp-org-guidelines.md (Guidelines 12/16/17) and field-notes.md §1 (sticky get_name()).

1. Default Assumptions

Quickly assess — only ask if the answer would change the code:

| Info needed | Ask only if... | |---|---| | Scope (plugin vs snippet vs child theme) | Context doesn't make it obvious | | Elementor tier (Free / Pro / custom widget) | Pro-only APIs are involved | | PHP version | Code uses PHP 8.3+ features like typed class constants, or 8.4+ features like property hooks | | WooCommerce / ACF / WPML present | Integration with those systems is required |

Default stack when not stated (full release-by-release history lives in CHANGELOG.md — keep volatile version-tracking out of this router):

| Component | Version | Notes | |---|---|---| | WordPress | 7.1 | "Mary Lou", released Aug 19, 2026 (7.0 "Armstrong" was May 20; the 7.0 branch ended at 7.0.4, Aug 12). Minimum PHP 7.4 (7.2/7.3 dropped — sites still on them stay pinned to 6.9.x). No multisite assumed. 7.1 makes the post editor iframe unconditional — see below. | | PHP | 8.3 recommended | 7.4 = minimum. 8.4 / 8.5 = "beta support" (possible deprecation notices). 8.2 fully compatible but no longer the recommended default. | | Elementor (free + Pro) | 4.2+ | Separate plugins with independent version numbers — currently free 4.2.3 / Pro 4.2.2 (both Aug 19, 2026). 4.0.0 (Mar 30, 2026) made the Atomic Editor stable + default for new installs; 4.2.0 (Jul 20) added Atomic Grid (free) and Atomic Loop (Pro). ⚠️ Elementor's header still reads "Tested up to: 7.0.4" — it has not declared WP 7.1 support. V3 Widget_Base remains fully supported — all skill code targets V3 and is production-safe. | | WooCommerce | 11.0+ | 11.0 (Aug 4, 2026) REMOVED the product editor beta and bumped to Action Scheduler 4.0.0 (breaking dedup change). HPOS default-on since 8.2; 10.7 disabled HPOS "sync on read"; 10.9 defers Store API draft-order creation — see woocommerce.md. |

Note: Elementor core and Elementor Pro have independent version numbers — always check both when diagnosing compatibility issues.

WordPress 7.1 — what changed for plugin / Elementor devs

WP 7.1 "Mary Lou" shipped August 19, 2026 (WordCamp US). Unlike 7.0, this release contains four changes that can break a shipped plugin — they are listed first. No PHP or WordPress minimum changed.

🔴 Breaking — audit your plugin for these:

The post editor is now ALWAYS in an iframe — including on sites registering legacy meta boxes, which was the last remaining escape hatch. Editor JavaScript that reaches for the global document / window now targets the wrong document. Use the canvas element's ownerDocument and defaultView instead:
```
// ❌ breaks in 7.1 — this is the OUTER document, not the editor canvas
document.querySelector( '.my-block' ).classList.add( 'ready' );

// ✅ resolve the document from a node you already own inside the canvas
const doc  = myCanvasNode.ownerDocument;
const view = doc.defaultView;                   // the iframe's `window`
doc.querySelector( '.my-block' )?.classList.add( 'ready' );
view.requestAnimationFrame( … );
```
Injected <style>/<link> must go into the canvas document too, or it styles nothing. Elementor's own editor is unaffected (it is not the block editor) — this hits block registrations, meta boxes, and any block-editor integration your plugin ships.
__next40pxDefaultSize is now a no-op on @wordpress/components — remove the prop entirely; there is no replacement. Form controls render at 40px unconditionally.
List-table markup changed: the row header moved from the checkbox column to the title column. Any CSS/JS selector keyed on th.check-column (or assuming the row header's position) breaks — audit custom admin list tables and column callbacks.
jQuery UI updated to 1.14.2. Test anything depending on jQuery UI behaviour or styling.

🟢 New and useful:

SVG Icon API (public in 7.1) — register icons and whole collections, render server-side, read over REST: wp_register_icon_collection(), wp_register_icon(), wp_get_icon(). ⚠️ SVGs pass through a conservative allowlist — only <svg>, <path> and <polygon> survive. A <g>, <circle>, <rect> or <use> in your icon is stripped silently, so convert shapes to paths before registering. (This is a core API — Elementor widgets still ship their own SVGs; see elementor-extending.md §8 and the "don't wp_kses() inline SVG" rule in field-notes.md §6.)
Abilities API matured: wp_get_abilities() filtering, execution-lifecycle hooks, custom validation, a unified public exposure flag, and client-compatible JSON-Schema preparation. Registration timing rules from 7.0 are unchanged (see the 7.0 section below).
Global Styles / theme.json: responsive style variations with configurable breakpoints, pseudo-state styling (:hover / :focus / :active), and text-shadow support.
Media: client-side image processing in the browser via WebAssembly (compression/resizing no longer hit the server), infinite scroll in the Media Library, and registration of multiple image sizes at once. Multisite now enforces upload limits on media sideloading.
Persistent admin bar across editor screens — review any custom toolbar nodes for behaviour in the editor context.
Design System: semantic design tokens for theming admin UI (relevant if you build admin or editor panels — compare the Elementor panel tokens in elementor-extending.md §5).
DataViews / DataForm APIs matured for data-driven admin interfaces.
React stays on 18.3 — React 19 was deferred again. Don't bundle react/jsx-runtime yourself, and avoid string refs / defaultProps, which fail under the experimental React 19 flag.
Conditional block-CSS loading can affect remote content pulls — verify if you render blocks outside a normal page request.

Sources: wordpress.org/news/2026/08/mary-lou/ · make.wordpress.org/core/2026/08/05/wordpress-7-1-field-guide/ · developer.wordpress.org/news/2026/08/whats-new-for-developers-august-2026/

WordPress 7.0 — what changed for plugin / Elementor devs

WP 7.0 "Armstrong" shipped May 20, 2026 (delayed from the original April 9 target while the RTC storage layer was redesigned — see below). Everything below is opt-in and non-breaking; most plugin/Elementor work is unaffected. It remains relevant because 7.1 changed none of it.

Minimum PHP is now 7.4 (7.2/7.3 dropped). The skill's recommended baseline stays PHP 8.3. Bump your plugin's Requires PHP header to 7.4 only once you target WP 7.0+ exclusively. No new DB minimum is enforced; wordpress.org/about/requirements/ recommends MariaDB 10.11+ or MySQL 8.0+ (the MariaDB floor was raised from 10.6; re-verified Aug 2026).
Real-Time Collaboration (RTC): simultaneous multi-author block editing (CRDT-based, via an HTTP-polling sync provider — not WebRTC). Data is stored in a dedicated core database table; an earlier wp_post_meta / wp_sync_storage design was rejected, and building the table is what pushed the release from April to May. Plugin impact: scope every WP_Query / get_posts() with an explicit post_type so internal core post types never leak into your results — do not hardcode any internal RTC type name. The WP_ALLOW_COLLABORATION constant lets hosts swap the sync transport.
WP AI Client: provider-agnostic PHP + JS AI API — wp_ai_client_prompt( $prompt )->generate_text(). Guard with function_exists( 'wp_ai_client_prompt' ).
Abilities API: wp_register_ability() (PHP, since WP 6.9) plus a JS counterpart in 7.0. Use 'meta' => ['show_in_rest' => true] to expose via REST. Register ONLY inside the wp_abilities_api_init hook (core renamed the feature plugin's abilities_api_init; categories go on wp_abilities_api_categories_init) or you get _doing_it_wrong; a category is required and must already be registered. Calling it also sets your real Requires at least floor to 6.9 — Plugin Check errors on the header and function_exists() guards don't count (see debugging.md §1).
Connectors UI (Settings → Connectors) for managing AI provider credentials, and a Command Palette in wp-admin.
Iframed editor was still conditional in 7.0 — 7.1 makes it unconditional. See the 7.1 section above; "apiVersion": 3 in block.json is now table stakes, not preparation.

Sources: make.wordpress.org/core/2026/01/09/dropping-support-for-php-7-2-and-7-3/ · make.wordpress.org/core/2026/04/22/wordpress-7-0-release-party-updated-schedule/ · wordpress.org/about/requirements/

📌 PHP support labels (unchanged in WP 7.1): PHP 7.4–8.3 fully compatible; 8.3 recommended; 8.4 (WP 6.7+) and 8.5 (WP 6.9+) carry a "beta support" label (possible deprecation notices). Source: make.wordpress.org/core/handbook/references/php-compatibility-and-wordpress-versions/

✅ Elementor 4.x status (current: free 4.2.3 / Pro 4.2.2, both Aug 19, 2026): Elementor 4.0.0 (Mar 30, 2026, free + Pro) made the Atomic Editor stable and the default for new installs and added Atomic Forms, Pro Interactions, and Component creation. Updating to 4.x leaves existing sites untouched — V3 widgets and V4 Atomic Elements coexist on the same page; Atomic features are toggled at WP Admin → Elementor → Editor → Settings.

There is still NO third-party API for building Atomic Elements, and Elementor has said so explicitly — they will not release one soon and advise against integrating with Atomic internals until they announce it (elementor/elementor GitHub Discussion #32950). Atomic Elements are documented only as a data structure (developers.elementor.com/docs/data-structure/atomic-elements). So continue using V3 Widget_Base for all third-party widgets — it is the correct, production-safe API and all skill code targets it. (Re-verified Aug 23, 2026 — unchanged since the July check.)

⚠️ Elementor has not declared WP 7.1 compatibility yet. As of free 4.2.3 / Pro 4.2.2 the Tested up to header reads 7.0.4, three days after WP 7.1 shipped. That is normal lag, not a known incompatibility — but when a client reports editor breakage on a fresh 7.1 site, check Elementor's current Tested up to before debugging your own code.

V4 Atomic Elements that now ship by default (awareness only — not third-party-buildable yet): Div Block & Flexbox Container (layout); Atomic Grid — advanced row/column layouts (free 4.2.0, Jul 20, 2026); Atomic Heading, Paragraph, Image, Button, Video, SVG; Atomic Tabs; Atomic Forms (Pro) with composable fields — Label, Input, Textarea, Checkbox, Submit, plus Radio, Select, Date Picker, Time Picker, and File Upload (added in Pro 4.1.0, May 26, 2026); and Atomic Loop — dynamic content layouts, the V4 counterpart of the Pro Loop Grid (Pro 4.2.0, Jul 20, 2026). These are end-user elements; building custom atomic elements still awaits the finalized V4 extension docs — keep targeting V3 Widget_Base until then. Source: elementor.com/products/website-builder/v4-faq/ · developers.elementor.com/elementor-editor-4-0-developers-update/ · elementor.com/pro/changelog/ · github.com/elementor/elementor/releases

🗓️ Release-by-release history (betas, RCs, point releases) lives in CHANGELOG.md. Keep this router focused on durable guidance; update version facts in the table above and in CHANGELOG.md, not scattered across the sub-files.

2. Architecture Decision Tree

Run through this mentally before writing a single line:

Does a WordPress core hook (add_action/add_filter) solve it?
  YES → Use the hook. No plugin needed. Place in child theme functions.php
        or Elementor Custom Code.
  NO  → Does Elementor's PHP/JS API solve it?
          YES → Extend via Elementor hooks, Dynamic Tags, or Widget_Base.
                Register via elementor/widgets/register or elementor/dynamic_tags/register.
          NO  → Is this logic reusable across themes or sites?
                  YES → Scaffold a dedicated plugin (see scaffolding.md).
                  NO  → Child theme functions.php or Elementor Custom Code block.

Is a WooCommerce override needed?
  → Use Elementor Loop Grid + custom query filter BEFORE touching template files.
  → Only override woocommerce/ templates as an absolute last resort.

Is this a REST API endpoint?
  → Always register via register_rest_route() inside a plugin, never in functions.php.

3. Mandatory Output Format

Every single code response must follow this structure — no exceptions:

📍 PLACEMENT
Exact file path or Elementor hook location.
e.g. /wp-content/plugins/myplugin/includes/class-myplugin-hooks.php
     Elementor → Site Settings → Custom Code → wp_footer

⚙️ REQUIRES
WordPress X.X+ | PHP X.X+ | Elementor Pro X.X+ | ACF X.X+ | WooCommerce X.X+
(list only what the code actually depends on)

💡 WHY THIS APPROACH
One paragraph: which branch of the §2 decision tree was taken and why.

📋 CODE
Complete, commented, deployment-ready code block — no truncation, no omissions.

🔧 INTEGRATION NOTES (include when relevant)
Any manual steps required: flush rewrite rules, set Query ID in Elementor editor,
activate plugin, clear Elementor cache, etc.

4. Quick Reference — Pattern Index

| Task | Approach | Sub-file | |---|---|---| | Plugin scaffold | Singleton + hooks class + assets class + HPOS declaration | scaffolding.md | | Child theme setup | wp_enqueue_style parent + child in functions.php | scaffolding.md | | Custom Post Type + Taxonomy | register_post_type() + register_taxonomy() in plugin | scaffolding.md | | Secure AJAX handler | wp_ajax_ hooks + nonce verify + wp_send_json_* | scaffolding.md | | PHP sanitization / escaping | wp_unslash() + sanitize_* + esc_* patterns | php-standards.md | | Transient caching | get_transient / set_transient | php-standards.md | | External API call + WP_Error | wp_remote_get() + WP_Error pattern | php-standards.md | | Admin settings page | Settings API + register_setting + sanitize_callback + settings_fields | wordpress-apis.md | | Store plugin options | Options API + explicit boolean autoload (WP 6.6+) | wordpress-apis.md | | Custom field exposed to REST / Elementor | register_post_meta + show_in_rest | wordpress-apis.md | | Scheduled / background task | WP-Cron (wp_schedule_event) + Action Scheduler for heavy jobs | wordpress-apis.md | | Create a custom DB table | dbDelta() + $wpdb->prefix + get_charset_collate(); strict formatting rules | mariadb.md | | "Specified key was too long" / emoji not saving | utf8mb4 + index string columns at varchar(191) | mariadb.md | | Slow query / missing index | EXPLAIN (type: ALL, key: NULL, Using filesort) + leftmost-prefix rule | mariadb.md | | SQL that must run on MariaDB and MySQL | Plain standard SQL; JSON is stored/compared differently — don't query inside it | mariadb.md | | Make a plugin translatable | i18n functions + text-domain = slug + WP 6.7 init-timing rule | wordpress-apis.md | | Ship a translation for a wp.org-hosted plugin | .pot only in the zip; translate.wordpress.org → language packs (90% gate). Never bundle .mo / call load_plugin_textdomain() | wordpress-apis.md | | Style UI text for non-Latin locales | Caseless scripts + text-transform/letter-spacing; don't size to English string length | js-css-standards.md | | Test that translations actually load | Set the site locale before bootstrap; unload_textdomain() in WP-CLI; validate placeholders | debugging.md | | Deploy / tag a plugin release on wp.org SVN | svn co → copy to trunk/ → svn cp trunk tags/X.Y.Z → svn ci (assets/ is a sibling) | svn/svn.md | | Any SVN task (checkout, commit, branch, merge, conflicts, repo admin) | Subversion sub-bundle | svn/svn.md | | WP 6.8 password hashing | wp_check_password() + wp_password_needs_rehash() | php-standards.md | | WP 6.8 app password / key hashing | wp_fast_hash() + wp_verify_fast_hash() (BLAKE2b) | php-standards.md | | JS standards + enqueue defer/async | IIFE + WP 6.3+ enqueue API | js-css-standards.md | | PHP → JS data passing | wp_add_inline_script() with wp_json_encode() | js-css-standards.md | | CSS BEM + design tokens | Scoped tokens, 8pt spacing, fluid type | js-css-standards.md | | Custom Elementor widget | Widget_Base + all required methods | elementor-patterns.md | | Elementor Dynamic Tag | Tag class + elementor/dynamic_tags/register | elementor-patterns.md | | Elementor Loop Grid query | elementor/query/ filter | elementor-patterns.md | | ACF field in Elementor | Dynamic Tag extending \Elementor\Core\DynamicTags\Tag | elementor-patterns.md | | Elementor Pro Form action | Action_Base + field iteration | elementor-patterns.md | | Theme Builder custom condition | Condition_Base + elementor/theme/register_conditions | elementor-patterns.md | | Elementor Pro custom form field | Field_Base + elementor_pro/forms/fields/register | elementor-extending.md | | Theme Builder custom location | register_location + elementor_theme_do_location() | elementor-extending.md | | Add a control to a NATIVE Elementor widget | elementor/element/{el}/{section}/before_section_end | elementor-extending.md | | Filter a native widget's output | elementor/widget/render_content filter | elementor-extending.md | | Add a TAB to the editor panel (like an SEO plugin) | elementorV2.editorElementsPanel.injectTab() + elementor/editor/before_enqueue_scripts | elementor-extending.md | | WooCommerce HPOS compatibility | FeaturesUtil::declare_compatibility() + wc_get_order() | woocommerce.md | | WooCommerce loop | Loop Grid + elementor/query/ filter | woocommerce.md | | Custom REST endpoint | register_rest_route() + schema callback in plugin | rest-api.md | | Off-canvas filter panel | BEM CSS + ARIA JS + Custom Code block | offcanvas-ui.md | | Performance checklist | Frontend + backend checklists | performance.md | | Accessibility checklist | WCAG 2.2 AA patterns | performance.md | | Elementor dependency check | Requires Plugins: elementor header + did_action fallback | scaffolding.md | | Widget with button/CTA | Controls + render matching native Button widget | widget-button.md | | Widget with container/layout | Controls + render matching native Container | widget-container.md | | Widget with image | Group_Control_Image_Size + get_attachment_image_html() | widget-image.md | | Widget with heading | TEXTAREA + header_size tag selector | widget-heading.md | | Widget with rich text | WYSIWYG + wp_kses_post output | widget-text-editor.md | | Widget with video embed | Source SELECT + overlay + aspect ratio | widget-video.md | | Widget rendering saved Elementor template | get_builder_content_for_display() + SELECT2 | widget-elementor-template.md | | Widget with PHP template file | load_template() + locate_template() strategies A/B/C | widget-php-template.md | | Widget with divider line | Style + width + optional text/icon element | widget-divider.md | | Widget with spacer gap | Single responsive SLIDER | widget-spacer.md | | Widget with single icon | ICONS control + size + color tabs | widget-icon.md | | Widget with icon + text box | Icon + title + description pattern | widget-icon-box.md | | Widget with image + text box | Image + title + description pattern | widget-image-box.md | | Widget with image grid | GALLERY control + Group_Control_Image_Size | widget-image-gallery.md | | Widget with image slider | GALLERY + Swiper + navigation controls | widget-image-carousel.md | | Widget with icon bullet list | REPEATER + icon + text + optional link | widget-icon-list.md | | Widget with animated counter | Number + prefix/suffix + duration | widget-counter.md | | Widget with progress bar | Percentage SLIDER + bar styling | widget-progress.md | | Widget with testimonial quote | Content + image + name + job title | widget-testimonial.md | | Widget with tabbed panels | REPEATER tabs + horizontal/vertical type | widget-tabs.md | | Widget with accordion | REPEATER + single-open collapse pattern | widget-accordion.md | | Widget with toggle panels | REPEATER + multi-open toggle pattern | widget-toggle.md | | Widget with social icons | REPEATER + brand icons + links | widget-social-icons.md | | Widget with alert/notice box | Type SELECT + title + description + dismiss | widget-alert.md | | Widget with audio player | SoundCloud URL + autoplay options | widget-audio.md | | Widget outputting shortcode | TEXTAREA + do_shortcode() | widget-shortcode.md | | Widget with raw HTML embed | CODE control + unescaped output | widget-html.md | | Widget as named anchor | TEXT ID + sanitize_html_class() | widget-menu-anchor.md | | Widget outputting sidebar | Registered sidebar SELECT + dynamic_sidebar() | widget-sidebar.md | | Widget with read more tag | No controls — WordPress $more global | widget-read-more.md | | Widget with Google Maps | Address TEXT + zoom SLIDER + iframe | widget-google-maps.md | | Widget with star rating display | Scale + rating number + icon style | widget-star-rating.md | | Widget with schema rating | Icon count + fractional rating + gap | widget-rating.md | | Widget with curved/path text | <svg> + <textPath> + unique path id | widget-text-path.md | | Nested Tabs / Accordion widget | Widget_Nested_Base + print_child() + container panels | widget-nested.md |

5. Mandatory Widget Controls — No Hardcoded Visuals (NEVER VIOLATE)

This section is MANDATORY for every custom Elementor widget. Whenever you build a widget, every visual property must be an Elementor control — NEVER a hardcoded CSS value. Users control appearance from the editor panel/toolbar, not by editing source code.

The Rule

NEVER hardcode any of the following in PHP render(), in static CSS, or in content_template() output:

Colors (text, background, border, shadow)
Typography (font family, size, weight, line-height, letter-spacing, transform)
Spacing (padding, margin, gap)
Sizing (width, height, min/max values)
Borders (style, width, color, radius)
Shadows (box-shadow, text-shadow)
Backgrounds (color, gradient, image)
Alignment / positioning
Opacity, transitions, hover effects

ALL of the above must use Elementor controls with selectors that inject CSS dynamically. The only exceptions are structural CSS (display, position, overflow) required for the widget layout to function at all — and even these should use controls when there is a user-facing choice (e.g. flex-direction toggle).

⚠️ "No hardcoded visuals" does NOT mean "put a default on every control." Elementor emits a default exactly like a user-set value, so a colour default paints on every install and clearing the swatch only restores it — the user cannot turn it off. Elementor core carries no default on colour controls at all (includes/widgets/heading.php: title_color uses a 'global' reference; title_hover_color is entirely empty). Follow that split:

Sizes, spacing, alignment, toggles, tags, labels → give a real 'default'.

Colours → leave empty. Put the resting look in your stylesheet's var(--token, fallback) and let the control override it. For state colours (hover / active / selected / current) also write a direct CSS property, never a custom property, and keep that state colour-free in your CSS — otherwise "empty" still paints the fallback.

See field-notes.md §4 for the full trap, plus the theme-specificity and accent-color cases.

Required Controls Checklist — Apply to Every Widget

When building a widget, include ALL controls that apply to its visual elements. Use this checklist as a mandatory gate:

| Visual property | Required Elementor control | Tab | |---|---|---| | Text content | TEXT, TEXTAREA, or WYSIWYG + 'dynamic' => ['active' => true] | TAB_CONTENT | | Typography (any text element) | add_group_control( Group_Control_Typography::get_type() ) | TAB_STYLE | | Text color | COLOR control with selectors | TAB_STYLE | | Text alignment | add_responsive_control() with CHOOSE (left/center/right/justify) | TAB_STYLE or TAB_CONTENT | | Background | add_group_control( Group_Control_Background::get_type() ) | TAB_STYLE | | Border | add_group_control( Group_Control_Border::get_type() ) | TAB_STYLE | | Border radius | add_responsive_control() with DIMENSIONS + 'selectors' | TAB_STYLE | | Box shadow | add_group_control( Group_Control_Box_Shadow::get_type() ) | TAB_STYLE | | Text shadow | add_group_control( Group_Control_Text_Shadow::get_type() ) | TAB_STYLE | | Padding | add_responsive_control() with DIMENSIONS | TAB_STYLE | | Margin | add_responsive_control() with DIMENSIONS | TAB_STYLE | | Width / Height | add_responsive_control() with SLIDER | TAB_STYLE | | Spacing / Gap | add_responsive_control() with SLIDER | TAB_STYLE | | Image | MEDIA + add_group_control( Group_Control_Image_Size::get_type() ) | TAB_CONTENT | | CSS Filters (if image/element) | add_group_control( Group_Control_Css_Filter::get_type() ) | TAB_STYLE | | Hover state | Duplicate color/background/shadow controls inside 'section_style_hover' with selectors targeting :hover | TAB_STYLE | | Transition duration | SLIDER (seconds) with selectors => ['transition-duration'] | TAB_STYLE | | Link | URL control with 'dynamic' => ['active' => true] | TAB_CONTENT | | Icon | ICONS control with fa4compatibility | TAB_CONTENT | | HTML tag | SELECT (h1–h6, div, span, p) | TAB_CONTENT |

Example — Correct vs Incorrect

// ❌ WRONG — hardcoded color and font-size
protected function render(): void {
    $settings = $this->get_settings_for_display();
    echo '<h2 style="color: #e94560; font-size: 24px;">'
        . esc_html( $settings['title'] ) . '</h2>';
}

// ✅ CORRECT — all visuals controlled from the panel via selectors
protected function register_controls(): void {
    // ... Content section with title TEXT control ...

    $this->start_controls_section( 'section_title_style', [
        'label' => esc_html__( 'Title Style', 'myplugin' ),
        'tab'   => \Elementor\Controls_Manager::TAB_STYLE,
    ] );

    $this->add_control( 'title_color', [
        'label'     => esc_html__( 'Color', 'myplugin' ),
        'type'      => \Elementor\Controls_Manager::COLOR,
        'selectors' => [
            '{{WRAPPER}} .myplugin-widget__title' => 'color: {{VALUE}};',
        ],
    ] );

    $this->add_group_control(
        \Elementor\Group_Control_Typography::get_type(),
        [
            'name'     => 'title_typography',
            'selector' => '{{WRAPPER}} .myplugin-widget__title',
        ]
    );

    $this->add_responsive_control( 'title_align', [
        'label'   => esc_html__( 'Alignment', 'myplugin' ),
        'type'    => \Elementor\Controls_Manager::CHOOSE,
        'options' => [
            'left'   => [ 'title' => esc_html__( 'Left',   'myplugin' ), 'icon' => 'eicon-text-align-left' ],
            'center' => [ 'title' => esc_html__( 'Center', 'myplugin' ), 'icon' => 'eicon-text-align-center' ],
            'right'  => [ 'title' => esc_html__( 'Right',  'myplugin' ), 'icon' => 'eicon-text-align-right' ],
        ],
        'selectors' => [
            '{{WRAPPER}} .myplugin-widget__title' => 'text-align: {{VALUE}};',
        ],
    ] );

    $this->add_responsive_control( 'title_spacing', [
        'label'      => esc_html__( 'Bottom Spacing', 'myplugin' ),
        'type'       => \Elementor\Controls_Manager::SLIDER,
        'size_units' => [ 'px', 'em', 'rem' ],
        'range'      => [ 'px' => [ 'min' => 0, 'max' => 100 ] ],
        'selectors'  => [
            '{{WRAPPER}} .myplugin-widget__title' => 'margin-bottom: {{SIZE}}{{UNIT}};',
        ],
    ] );

    $this->end_controls_section();
}

protected function render(): void {
    $settings = $this->get_settings_for_display();
    // ✅ No inline styles — all visuals come from Elementor's selectors
    $this->add_render_attribute( 'title', 'class', 'myplugin-widget__title' );
    $this->add_inline_editing_attributes( 'title' );
    echo '<h2 ' . $this->get_render_attribute_string( 'title' ) . '>'
        . esc_html( $settings['title'] ) . '</h2>';
}

`add_render_attribute()` and `add_inline_editing_attributes()` — Always Use

The official Elementor API for building HTML attributes is $this->add_render_attribute(). Always use it instead of manually concatenating class/id/aria attributes in render(). Pair with $this->add_inline_editing_attributes() for any text field that supports live editing in the Elementor editor panel.

Outputting the built attributes — pick by context: use get_render_attribute_string( 'key' ) when you are concatenating into a string (as in the echo '<h2 ' . ... . '>' example above), and print_render_attribute_string( 'key' ) when you are echoing directly inside a ?> … <?php HTML block (e.g. <h2 <?php $this->print_render_attribute_string( 'title' ); ?>>). Both are correct Elementor APIs — print_* simply echoes what get_* returns. The widget sub-files use the print_* form inside their HTML templates.

Source: developers.elementor.com/docs/widgets/rendering-html-attribute/ Source: developers.elementor.com/docs/widgets/rendering-inline-editing/