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

:::::tip Version Availability
This class is available starting from v3.11.0
:::::

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

```typescript
class ExternalMergeTagsLibrary
```

## Description

`ExternalMergeTagsLibrary` enables integration of your own catalog of merge tags into the input fields of the Stripo Email Editor. When a library is registered, the editor opens it instead of the built-in merge tags picker in the following places:

* The merge tag icon of text inputs in the settings panel (for example, button text, image alt text, menu and social items, UTM parameters) and of [RICH\_TEXT](../constants/UIElementType#rich-text) UI elements with the `has-merge-tag-icon` attribute
* The merge tag icon of link fields
* The merge tag icon of the image path field
* The **Insert merge tag** option of the email Subject and Hidden Preheader fields

The merge tags selector of the text block is not affected by this class. To replace it, override `UIElementType.MERGETAGS` with a custom UI element as shown in the [External Merge Tags Selector](/extensions/tutorials/examples/integrations/external-merge-tags-selector) tutorial. Both integrations can be used side by side.

## Import

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

## Properties

### api

```typescript
api: BaseApi
```

#### Type

[BaseApi](../api/BaseApi.md)

The API instance providing access to editor configuration, translations, and other core functionality. Automatically injected by the framework.

## Methods

### openMergeTagsLibrary()

Opens the external merge tags library interface for merge tag selection.

```typescript
openMergeTagsLibrary(
  currentValue: string,
  onSelectCallback: ExternalMergeTagSelectCallback,
  onCancelCallback: ExternalMergeTagCancelCallback,
  context: ExternalMergeTagsContext
): void
```

#### Parameters

| Name | Type | Description |
|------|------|-------------|
| currentValue | `string` | Current value of the whole field the library is opened for (e.g., input text or link URL) |
| onSelectCallback | `ExternalMergeTagSelectCallback` | Called with the merge tag value when user selects a merge tag |
| onCancelCallback | `ExternalMergeTagCancelCallback` | Called when user cancels |
| context | `ExternalMergeTagsContext` | Information about the field the library is opened for |

#### Usage Notes

* The selected value is inserted as-is: in text fields, at the cursor position (limited by the field's maximum length); in link fields, it replaces the whole URL
* Only the first call of `onSelectCallback` or `onCancelCallback` is taken into account
* If the method throws an error, the editor falls back to the built-in merge tags picker

## Type Definitions

### ExternalMergeTagsContext

Describes the field the library is opened for.

```typescript
interface ExternalMergeTagsContext {
  fieldType: ExternalMergeTagsFieldType;
  fieldName?: string;
}
```

| Property | Type | Description |
|----------|------|-------------|
| fieldType | `ExternalMergeTagsFieldType` | `'link'` for link fields, `'text'` for all other fields (text inputs, image path, Subject, Hidden Preheader) |
| fieldName | `string` | (Optional) Identifier of the field. For [RICH\_TEXT](../constants/UIElementType#rich-text) UI elements, it equals the element's `name` attribute |

### ExternalMergeTagsFieldType

Type of the field the library is opened for.

```typescript
type ExternalMergeTagsFieldType = 'text' | 'link';
```

### Callback Types

```typescript
type ExternalMergeTagSelectCallback = (value: string) => void;
type ExternalMergeTagCancelCallback = () => void;
```

## Example

```typescript
import {
  ExtensionBuilder,
  ExternalMergeTagCancelCallback,
  ExternalMergeTagSelectCallback,
  ExternalMergeTagsContext,
  ExternalMergeTagsLibrary,
} from '@stripoinc/ui-editor-extensions';
import { MergeTagsModal } from './MergeTagsModal'; // your own modal implementation

class MyMergeTagsLibrary extends ExternalMergeTagsLibrary {
  openMergeTagsLibrary(
    currentValue: string,
    onSelectCallback: ExternalMergeTagSelectCallback,
    onCancelCallback: ExternalMergeTagCancelCallback,
    context: ExternalMergeTagsContext
  ): void {
    // Offer only URL merge tags for link fields
    const mergeTags = context.fieldType === 'link'
      ? [{ label: this.api.translate('Profile page'), value: '*|PROFILE_URL|*' }]
      : [
          { label: this.api.translate('First Name'), value: '*|FNAME|*' },
          { label: this.api.translate('Last Name'), value: '*|LNAME|*' }
        ];

    new MergeTagsModal(mergeTags).open({
      onSelect: (mergeTag) => onSelectCallback(mergeTag.value),
      onClose: () => onCancelCallback()
    });
  }
}

export default new ExtensionBuilder()
  .withExternalMergeTagsLibrary(MyMergeTagsLibrary)
  .build();
```

**Full Example Implementation:** [How to Integrate External Merge Tags](/extensions/tutorials/examples/integrations/external-merge-tags-selector) — one merge tags modal shared by the text block and input fields.