UIElement

Core class for creating custom UI elements in the Stripo Email Editor.

class UIElement

Description

UIElement is the foundation for building custom user interface components that can be embedded within the Stripo Email Editor's controls and panels. These elements provide interactive functionality beyond standard HTML elements, such as custom inputs, color pickers, dropdowns, or any specialized UI component your extension requires.

UI elements are rendered dynamically when needed and can maintain state, respond to attribute changes, and integrate seamlessly with the editor's control system. They're particularly useful when building complex controls that require custom interaction patterns not available in standard HTML form elements.

Import

import { UIElement } from '@stripoinc/ui-editor-extensions';

Properties

api

Provides access to editor functionalities specific to this UI element instance.

public api!: UIElementApi

Type

UIElementApi

Usage Notes

• Automatically injected by the editor when the element is instantiated
• Provides methods for dispatching events and accessing editor state
• Available after the element is registered

Methods

getId()

Returns the unique identifier for this UI element type.

getId(): string

Returns

string - A unique identifier for the UI element

Usage Notes

• Must be unique across all registered UI elements
• Used for registration and referencing within controls

Example

public getId(): string {
  return 'brand-color-picker';
}

---

getTemplate()

Returns the HTML template string that defines the structure of this UI element.

getTemplate(): string

Returns

string - HTML template for the element

Usage Notes

• Defines the initial HTML structure
• Can use custom attributes that will be managed by the element
• Should be a valid HTML fragment

Example

public getTemplate(): string {
  return `
    <div class="custom-color-picker">
      <div class="color-preview"></div>
      <button class="picker-button">Choose Color</button>
    </div>
  `;
}

---

onRender()

Called when the UI element should render its content into the provided container.

abstract onRender(container: HTMLElement): void

Parameters

Name	Type	Description
container	HTMLElement	The DOM element where the UI element should be rendered

Usage Notes

• This is where you set up event listeners and initialize the element
• The container already contains the HTML from getTemplate()
• Store references to DOM elements for later use

Example

public onRender(container: HTMLElement): void {
  const button = container.querySelector('.picker-button');
  const preview = container.querySelector('.color-preview');

  button?.addEventListener('click', () => {
    this.openColorPicker();
  });

  // Initialize with current value
  if (this.currentColor) {
    preview.style.backgroundColor = this.currentColor;
  }
}

onDestroy()

Cleanup hook called when the UI element is being destroyed.

onDestroy(): void

Usage Notes

• Remove event listeners added in onRender()
• Clear timers or intervals
• Clean up any external resources
• Prevent memory leaks

Example

public onDestroy(): void {
  // Remove event listeners
  if (this.clickHandler) {
    this.button?.removeEventListener('click', this.clickHandler);
  }

  // Clear any timers
  if (this.updateTimer) {
    clearInterval(this.updateTimer);
  }
}

---

getValue()

Returns the current value of the UI element.

getValue(): any

Returns

any - The current value of the element

Usage Notes

• Implement if your element manages state or value
• Called by the editor to retrieve the element's current value
• Return type depends on your element's purpose

Example

public getValue(): string {
  return this.selectedColor || '#000000';
}

---

setValue()

Sets the value of the UI element.

setValue(value: any): void

Parameters

Name	Type	Description
value	any	The new value to set

Usage Notes

• Implement if your element needs to be updated externally
• Update the UI to reflect the new value
• Validate the value if necessary

Example

public setValue(value: string): void {
  if (this.isValidColor(value)) {
    this.selectedColor = value;
    this.updatePreview(value);
  }
}

---

onAttributeUpdated()

Called when one of the element's supported attributes gets updated externally.

onAttributeUpdated(name: string, value: unknown): void

Parameters

Name	Type	Description
name	string	The name of the attribute that was updated
value	unknown	The new value of the attribute

Usage Notes

• React to attribute changes like visibility or disabled state
• Supported attributes are defined in UEAttr
• Update the UI accordingly

Example

export class CustomSlider extends UIElement {
    getId() {
        return 'custom-slider';
    }

    onAttributeUpdated(name, value) {
        if (name === 'disabled' && value === true) {
            console.log('Slider is disabled');
        }
        super.onAttributeUpdated(_name, _value);
    }
    
    //Additional configuration
}

class CustomControl extends UIElement {
    getTemplate() {
        return `
          <div class="custom-slider-container">
            <custom-slider name="custom-slider-name"></custom-slider>
          </div>
        `;
    }

    onRender(container) {
        this.api.setUIEAttribute('custom-slider-name',
            'disabled',
            true);
    }

    //Additional configuration
}