ExternalImageLibrary

Core class for integrating external image libraries with the Stripo Email Editor.

class ExternalImageLibrary

Description

ExternalImageLibrary enables integration of third-party image storage and management services (like Cloudinary, Unsplash, or custom DAM systems) into the Stripo Email Editor. This interface allows users to browse, search, and select images from external sources directly within the editor, streamlining the workflow for adding images to email templates.

Import

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

Methods

openImageLibrary()

Opens the external image library interface for image selection.

openImageLibrary(
  currentImageUrl: string,
  onImageSelectCallback: ExternalGalleryImageSelectCallback,
  onCancelCallback: ExternalGalleryImageCancelCallback
): void

Parameters

Name	Type	Description
currentImageUrl	string	URL of the currently selected image (if any)
onImageSelectCallback	ExternalGalleryImageSelectCallback	Called when user selects an image
onCancelCallback	ExternalGalleryImageCancelCallback	Called when user cancels

Type Definitions

Callback Types

type ExternalGalleryImageSelectCallback = (image: ExternalGalleryImage) => void;
type ExternalGalleryImageCancelCallback = () => void;

ExternalGalleryImage

Represents an image from the external gallery.

interface ExternalGalleryImage {
  originalName: string;    // Original filename (e.g., 'product-photo.png')
  width: number;           // Width in pixels
  height: number;          // Height in pixels
  sizeBytes: number;       // File size in bytes
  url: string;             // Full URL to the image
  altText: string;         // Alt text for accessibility
  labels?: Record<string, string>;  // Metadata displayed in the editor (v3.2.0+)
  thumbnailUrl?: string;   // Optional preview URL (v3.11.0+)
  customParams?: Record<string, string>;  // Integration data passed to onImageSelected (v3.11.0+)
}

Version Availability

The labels property is available starting from v3.2.0. The thumbnailUrl and customParams properties are available starting from v3.11.0 and are passed through to the onImageSelected callback together with the other image properties.

labels vs customParams

Both properties are optional Record<string, string> objects, but they serve different purposes. Use labels for information users should see while editing an image, and customParams for data your application needs when the image is selected. You can provide either property or both; all values must be strings.

Behavior	labels	customParams
Typical content	Author, license, category, source	Asset ID, storage record ID, hash
Displayed in the editor	Yes, as key: value entries in the image information panel	No
Stored in the editor document model	Yes, in the image node configuration as imageLabels	Not automatically
Passed to onImageSelected	Yes, as params.labels	Yes, as params.customParams
Converted into HTML attributes	Not automatically	Not automatically

labels are saved with the relevant node and can be read back from the document model when the image settings are opened again. This metadata is separate from HTML attributes in the email.

customParams are passed through to your callback without being interpreted or displayed by the editor. Returning them from your image library does not automatically save them on the image node or make them available from the document after a reload. If you need an asset ID in the email HTML, explicitly write it with the callback's modifier.

Example: visible labels and application data

Inside your openImageLibrary() implementation, pass both properties when the user selects an image:

onImageSelectCallback({
  originalName: 'product-photo.png',
  width: 800,
  height: 600,
  sizeBytes: 102400,
  url: 'https://example.com/product-photo.png',
  altText: 'Product photo',
  labels: {
    Author: 'Jane Doe',
    License: 'Commercial',
  },
  customParams: {
    assetId: 'A-1024',
    hashcode: 'abc123',
  },
});

The image information panel displays Author: Jane Doe and License: Commercial. The asset ID and hash are available to your application through params.customParams, without appearing in that panel.

Add an onImageSelected handler to your editor initialization settings to save the asset ID as an HTML attribute:

const stripoConfig = {
  // Other editor initialization settings...
  onImageSelected: (params, modifier) => {
    const assetId = params.customParams?.assetId;
    if (assetId) {
      modifier.setAttribute('data-asset-id', assetId);
    } else {
      // Clear the previous asset ID when replacing the image with one without it.
      modifier.removeAttribute('data-asset-id');
    }
  },
};

For the image above, this handler adds data-asset-id="A-1024" to the inserted <img>. The hashcode remains callback data because the handler does not write it to the document.

onImageSelectCallback is the callback your external library calls to return the selected image. onImageSelected is the editor initialization callback that receives the metadata and a modifier targeting the <img> element. It runs for image insertion or replacement that writes to an <img>; it does not run for backgrounds applied only through CSS or a background attribute.