Element Registry: The JavaScript API

The element registry exposes four functions on window.wptElements. This global is available in the block editor when wpt-element-registry has been declared as a dependency in your index.asset.php.

resolve( elementNames )

Returns the definition objects for the requested elements. Use this when you need to read what controls are available for an element.

var elements = window.wptElements.resolve( ['heading', 'description'] );
// elements.heading.h2.controls -- controls for h2 variant
// elements.description.controls -- controls for flat element

If an element is not loaded (not declared in index.asset.php), resolve() returns an empty object for that element and logs a console warning. Your block falls through to the CSS fallback, it never crashes.

getCascadedValue( elementName, variant, controlName, blockOverrides )

Resolves the correct value for a single control through the four-layer cascade.

var fontSize = window.wptElements.getCascadedValue(
    'heading',                    // element name
    attributes.headingLevel,      // variant (e.g. 'h2')
    'fontSize',                   // control name
    attributes.elementOverrides   // block's stored overrides
);
// Returns: 'xl', '3xl', etc.

For flat elements (no variants), pass null as the variant:

var color = window.wptElements.getCascadedValue(
    'description', null, 'color', attributes.elementOverrides
);

buildElementClasses( elementName, variant, blockOverrides )

This is the function blocks use most. It resolves all controls for the element through the cascade and returns a ready-to-use BEM modifier class string to apply to the element’s DOM node.

var headingClasses = window.wptElements.buildElementClasses(
    'heading',
    attributes.headingLevel,
    attributes.elementOverrides
);
// Returns: 'wpt-heading--color-text wpt-heading--fontsize-3xl wpt-heading--fontweight-bold'

Apply these classes to the element alongside your block’s own BEM class:

el( attributes.headingLevel, {
    className: 'wpt-my-block__heading ' + headingClasses
}, attributes.heading || 'Placeholder heading' )

Always null-guard this call. If the element registry script is not loaded (edge case during editor boot), window.wptElements may be undefined:

var headingClasses = window.wptElements
    ? window.wptElements.buildElementClasses( 'heading', attr.headingLevel, attr.elementOverrides )
    : '';

getOverrideCount( elementName, variant, blockOverrides )

Returns the number of active overrides set on this block instance for a given element. Used to show a count badge on the override button in the inspector.

var count = window.wptElements.getOverrideCount(
    'heading',
    attributes.headingLevel,
    attributes.elementOverrides
);
// Returns: 0, 1, 2, etc.