Merge Tags

Insert dynamic personalization tokens into text content that get replaced with real values at send time.

React

import { useRef } from "react";
import { DragbleEditor, DragbleEditorRef } from "dragble-react-editor";

function MergeTagEditor() {
  const editorRef = useRef<DragbleEditorRef>(null);

  return (
    <DragbleEditor
      ref={editorRef}
      editorKey="db_your_key"
      editorMode="email"
      options={{
        mergeTags: {
          sort: true,
          customMergeTags: [
            {
              label: "First Name",
              value: "{{first_name}}",
              category: "Contact",
            },
            { label: "Last Name", value: "{{last_name}}", category: "Contact" },
            { label: "Email", value: "{{email}}", category: "Contact" },
            {
              label: "Company",
              value: "{{company}}",
              category: "Organization",
            },
            {
              label: "Unsubscribe URL",
              value: "{{unsubscribe_url}}",
              category: "Links",
            },
          ],
        },
      }}
    />
  );
}

Vue

<template>
  <DragbleEditor
    ref="editorRef"
    editor-key="db_your_key"
    editor-mode="email"
    :options="editorOptions"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { DragbleEditor } from "dragble-vue-editor";

const editorRef = ref<InstanceType<typeof DragbleEditor>>();

const editorOptions = {
  mergeTags: {
    sort: true,
    customMergeTags: [
      { label: "First Name", value: "{{first_name}}", category: "Contact" },
      { label: "Last Name", value: "{{last_name}}", category: "Contact" },
      { label: "Company", value: "{{company}}", category: "Organization" },
    ],
  },
};
</script>

Angular

import { Component, ViewChild } from "@angular/core";
import { DragbleEditorComponent } from "dragble-angular-editor";

@Component({
  selector: "app-merge-tag-editor",
  standalone: true,
  imports: [DragbleEditorComponent],
  template: `
    <dragble-editor
      #editor
      editorKey="db_your_key"
      editorMode="email"
      [options]="editorOptions"
    ></dragble-editor>
  `,
})
export class MergeTagEditorComponent {
  @ViewChild("editor") editorComp!: DragbleEditorComponent;

  editorOptions = {
    mergeTags: {
      sort: true,
      customMergeTags: [
        { label: "First Name", value: "{{first_name}}", category: "Contact" },
        { label: "Last Name", value: "{{last_name}}", category: "Contact" },
        { label: "Company", value: "{{company}}", category: "Organization" },
      ],
    },
  };
}

Vanilla JS

dragble.init({
  containerId: "editor-container",
  editorKey: "db_your_key",
  editorMode: "email",
  options: {
    mergeTags: {
      sort: true,
      customMergeTags: [
        { label: "First Name", value: "{{first_name}}", category: "Contact" },
        { label: "Last Name", value: "{{last_name}}", category: "Contact" },
        { label: "Company", value: "{{company}}", category: "Organization" },
        {
          label: "Unsubscribe URL",
          value: "{{unsubscribe_url}}",
          category: "Links",
        },
      ],
    },
  },
});

Users can insert merge tags using the merge tag button in the text toolbar.

Exclude default merge tags

Set excludeDefaults: true to remove all built-in merge tags and only show your custom tags:

mergeTags: {
  excludeDefaults: true,
  customMergeTags: [
    { label: 'First Name', value: '{{first_name}}', category: 'Contact' },
    { label: 'Coupon Code', value: '{{coupon_code}}', category: 'Promo' },
  ],
}

Update merge tags at runtime

Call setMergeTags() to replace the tag configuration without reinitializing the editor:

// React
editorRef.current?.editor?.setMergeTags({
  customMergeTags: [
    { label: "First Name", value: "{{first_name}}", category: "Contact" },
    { label: "Coupon Code", value: "{{coupon_code}}", category: "Promo" },
  ],
});

// Vanilla JS
dragble.setMergeTags({
  customMergeTags: [
    { label: "First Name", value: "{{first_name}}", category: "Contact" },
    { label: "Coupon Code", value: "{{coupon_code}}", category: "Promo" },
  ],
});

:::info Merge tags in links and images Merge tags also work inside link URLs. Users can insert {{unsubscribe_url}} as a button or link href from the link editor. They can also be used in dynamic image URLs to personalize images per recipient. :::

Merge tag groups

Tags are organized into collapsible groups in the dropdown using the category property. Tags with the same category are displayed together:

const customMergeTags = [
  { label: "First Name", value: "{{first_name}}", category: "Contact" },
  { label: "Last Name", value: "{{last_name}}", category: "Contact" },
  { label: "Company", value: "{{company}}", category: "Organization" },
  { label: "Plan Name", value: "{{plan_name}}", category: "Billing" },
  { label: "Amount Due", value: "{{amount_due}}", category: "Billing" },
];

You can also use nested MergeTagGroup objects for hierarchical grouping:

const customMergeTags = [
  {
    name: "Contact",
    mergeTags: [
      { label: "First Name", value: "{{first_name}}" },
      { label: "Last Name", value: "{{last_name}}" },
    ],
  },
  {
    name: "Billing",
    mergeTags: [
      { label: "Plan Name", value: "{{plan_name}}" },
      { label: "Amount Due", value: "{{amount_due}}" },
    ],
  },
];

Configuration reference

Property	Type	Default	Description
excludeDefaults	boolean	false	Hide built-in default merge tags
sort	boolean	false	Sort tags alphabetically within groups
customMergeTags	(MergeTag | MergeTagGroup)[]	[]	Custom merge tags to add

Method reference

Method	Returns	Description
setMergeTags(config)	void	Replace the merge tags configuration at runtime
getMergeTags()	Promise<(MergeTag | MergeTagGroup)[]>	Get the current merge tags list

Next steps

• Dynamic Images -- personalize images using merge tags in URLs
• Special Links -- add custom link types like unsubscribe
• Display Conditions -- show/hide rows based on merge tag values
• Custom Tools -- build tools that use merge tags in their renderer