Extend Variables

Extend variables

Scope: External — the full documented custom-variable outcome is shippable from a 3rd-party plugin via elementor/variables/register + style-schema/transformer hooks + your own package init(); no Core changes required. Modifying Elementor's built-in size types or their Pro gating is outside this skill and requires Core/Pro changes. Full split + disclaimer: skills-scope.md.

Implementation location

• PHP: third-party plugin repo; variable prop types, transformers, elementor/variables/register (e.g. My\Shadow_Variable_Prop_Type).
• Editor JS: registerVariableType in your editor package init() — see add-editor-package.
• Do not modify Elementor Core. Core registry: modules/variables/; editor package: packages/packages/core/editor-variables/.
• Runnable reference: examples/example-plugin/ (global-shadow-variable PHP + JS + box-shadow schema union).

Prerequisites

• e_atomic_elements — variables module loads with atomic widgets.
• e_variables / e_variables_manager — variables manager UI; REST may work without the manager UI — variables/overview.md.
• Register elementor/variables/register before WordPress init (hook fires on init).

Read first: variables/types.md, variables/api.md, fundamentals/prop-types.md, usage-in-props.md.

Checklist

1. PHP variable type — typically extends String_Prop_Type (or other Transformable_Prop_Type) with stable get_key():

class Shadow_Variable_Prop_Type extends String_Prop_Type {
    public static function get_key(): string {
        return 'global-shadow-variable';
    }
}

add_action( 'elementor/variables/register', function (
    \Elementor\Modules\Variables\Classes\Variable_Types_Registry $registry
) {
    $registry->register( Shadow_Variable_Prop_Type::get_key(), Shadow_Variable_Prop_Type::make() );
} );

2. Style schema union (required for style binding) — filter elementor/atomic-widgets/styles/schema so target style keys accept the new $$type. Mirror built-in patterns in Core Style_Schema / Size_Style_Schema. Example for box-shadow:

add_filter( 'elementor/atomic-widgets/styles/schema', function ( array $schema ) {
    if ( isset( $schema['box-shadow'] ) ) {
        $schema['box-shadow'] = Union_Prop_Type::create_from( $schema['box-shadow'] )
            ->add_prop_type( Shadow_Variable_Prop_Type::make() );
    }
    return $schema;
} );

If $schema[ $key ] is already a Union_Prop_Type (e.g. padding, margin, gap in Style_Schema), call ->add_prop_type() on it; do not wrap with Union_Prop_Type::create_from() — mirror Style_Schema::update_font_family().

3. PHP render transformer — elementor/atomic-widgets/styles/transformers/register if frontend must resolve stored id → var(--label). Reuse \Elementor\Modules\Variables\Transformers\Global_Variable_Transformer (Core shares one instance for color/font); subclass only when resolution differs. PropValues store id; CSS uses label — see api.md and usage-in-props.md. Label rules: max 50 chars, no spaces.
4. JS editor type (required for "Add Variable" UI) — registerVariableType with key, icon, propTypeUtil, fallbackPropTypeUtil, variableType, plus defaultValue / valueField / styleTransformer as needed. Call from your editor v2 package init() (not core register-variable-types.tsx). Example: docs/atomic-builder/examples/extend-variables.md.
   • Skip JS → PHP-only type works via REST / MCP / CSS but never appears in the Add Variable dropdown.
   • Hand-built bundle: call init() yourself; registerVariableType via window.elementorV2.editorVariables; createPropUtils via window.elementorV2.editorProps.createPropUtils (not an import) — see add-editor-package.
5. Storage adapter — extend Adapters\Prop_Type_Adapter if value encoding is non-standard.
6. Verify on active kit — REST elementor/v1/variables/* and MCP elementor/manage-global-variable confirm types already registered; they do not define new types.

Size gap (important)

PHP Style_Transformers registers Global_Variable_Transformer for color and font only. Size has no matching PHP styles transformer. Built-in size types in JS use EmptyTransformer; editor canvas uses StyleVariablesRenderer. New types needing var(--label) on canvas should pass explicit styleTransformer in registerVariableType.

Built-in keys: global-color-variable, global-font-variable, global-size-variable, global-custom-size-variable.

"(Pro)" on size is not only a PHP gate: free Core JS registers size keys with isActive: false + upsell CTA; Pro re-registers as active. Details: variables/types.md.

External implementation path

• Plugin hooks elementor/variables/register + style schema + transformers + editor registerVariableType.
• Optional CSS: filter elementor/variables/css_entry_additional.

Core reference paths (do not edit)

• modules/variables/classes/variable-types-registry.php, hooks.php, prop-types/*-variable-prop-type.php.
• Editor: packages/packages/core/editor-variables/.

See also

• extend-prop-types — prop type + transformer pairing
• add-editor-package — bundle + init() for JS registration