---
url: >-
  https://plugin.stripo.email/extensions/reference/integrations/ExternalImageLibrary.md
---
# ExternalImageLibrary

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

```typescript
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

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

## Methods

### openImageLibrary()

Opens the external image library interface for image selection.

```typescript
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

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

### ExternalGalleryImage

Represents an image from the external gallery.

```typescript
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+)
}
```

:::::tip 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](/editor-configuration/initialization-settings#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:

```typescript
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:

```javascript
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.