Merge Tags
Merge tags allow end-users to dynamically add content to their email. Merge tags can be inserted into a block of text by clicking on the "Merge Tags" button in the text editor toolbar. The button is not shown if no merge tags were passed when initializing Unlayer.
We support all types of merge tags. All templating engines are fully supported, whether it uses curly brackets {{ ... }} or square brackets [ ... ] or any other.
This is how it looks if you have merge tags.

Merge Tags
Basic Merge Tags
There are 2 ways host application can pass merge tags to Unlayer.
Option 1) You can pass merge tags during initialization like this:
unlayer.init({
mergeTags: {
first_name: {
name: "First Name",
value: "{{first_name}}",
sample: "John"
},
last_name: {
name: "Last Name",
value: "{{last_name}}",
sample: "Doe"
}
}
});
Option 2) You can pass merge tags after initialization like this:
unlayer.setMergeTags({
first_name: {
name: "First Name",
value: "{{first_name}}",
sample: "John"
},
last_name: {
name: "Last Name",
value: "{{last_name}}",
sample: "Doe"
}
});
Grouped Merge Tags
You can group a set of merge tags inside a sub-menu by passing another mergeTags
object inside one.
unlayer.init({
mergeTags: {
shipping_address: {
name: "Shipping Address",
mergeTags: {
street_1: {
name: "Street 1",
value: "{{shipping_address.address_1}}"
},
street_2: {
name: "Street 2",
value: "{{shipping_address.address_2}}"
},
city: {
name: "City",
value: "{{shipping_address.city}}"
},
state: {
name: "State",
value: "{{shipping_address.state}}"
},
zip: {
name: "Zip",
value: "{{shipping_address.zip}}"
}
}
}
}
});
Smart Merge Tags

Smart merge tags are more human-friendly. With this, users will be able to:
- easily identify merge tags within highlighted field
- see human-friendly names instead of code – e.g., Customer Name instead of {{customer.name}}
- select, replace, and style merge tags with one click
It's enabled by default, but you can turn this off.
unlayer.init({
features: {
smartMergeTags: false
}
});
Loops and Conditions
You can use the merge tags to add conditions and looping for dynamic content.
For example, if you want your users to create an order confirmation email template and show all products in that order, you would pass the "Products" merge tags along with some rules
. The before
and after
of the selected rule will be added before and after the block in the exported HTML.
This before
and after
can be used to create loops or if-then-else conditions. The syntax will depend on which templating engine the host application uses. In this example, we are using Mustache templating engine.
If you want to add conditions to display content to different segments of audience, check Display Conditions.
unlayer.init({
mergeTags: {
products: {
name: "Products",
rules: {
repeat: {
name: "Repeat for Each Product",
before: "{{#products}}",
after: "{{/products}}",
}
},
mergeTags: {
name: {
name: "Product Name",
value: "{{name}}"
},
image: {
name: "Product Image",
value: "{{image}}"
}
}
}
}
});
Specifying the rules
will add an additional icon to the blocks in the editor. This icon will be used to select the merge tag group and rules.

Once you click that icon, it will let users pick a merge tag group and a merge rule, and will show the available merge tags after selection. You can then use those tags any where inside that block.

Sample Preview
You can provide sample values for each merge tag so users can see what the actual email would look like when the values are filled. These sample values are only visible in preview mode.
Simply add a sample
attribute to the merge tag. In the example below, {{first_name}}
will be replaced with John
and {{last_name}}
will be replaced with Doe
in preview mode.
unlayer.init({
mergeTags: {
first_name: {
name: "First Name",
value: "{{first_name}}",
sample: "John"
},
last_name: {
name: "Last Name",
value: "{{last_name}}",
sample: "Doe"
}
}
});
Autocomplete Menu Trigger
By default, the merge tag autocomplete menu is triggered by the first character of your merge tags. For example, if your merge tags look like {{first_name}}, the trigger will automatically be {
.
If you want to change the trigger character, you can do that like this.
unlayer.init({
mergeTagsConfig: {
autocompleteTriggerChar: "@"
}
});
Sorting Merge Tags
By default, merge tags are sorted alphabetically in the menu. You can disable sorting.
unlayer.init({
mergeTagsConfig: {
sort: false
},
})
Replacing with Real Values
When are Merge Tags replaced?
Replacing merge tags with actual values is done at the time of sending the email by the host application. Usually, the HTML should be parsed by your templating engine (Mustache, Nunjucks, etc) and the tags are replaced with real values.
In case you want to replace merge tags with real values at the time of exporting HTML, you can use the following examples.
Values
Replace {{first_name}}
with John
and {{last_name}}
with Doe
.
unlayer.exportHtml(function(data) {
var json = data.design;
var html = data.html;
}, {
mergeTags: {
first_name: 'John',
last_name: 'Doe'
}
})
Conditions
The following example can be used to show or hide a block based on a true | false
condition.
unlayer.exportHtml(function(data) {
var json = data.design;
var html = data.html;
}, {
mergeTags: {
products: {
empty: true
}
}
})
Loops
The following example can be used to provide data to a loop.
unlayer.exportHtml(function(data) {
var json = data.design;
var html = data.html;
}, {
mergeTags: {
products: {
repeat: [
{ name: 'Item 01' },
{ name: 'Item 02' }
]
}
}
})
Custom UI
You can extend this feature and allow users of the editor to build or choose merge tags using a UI that you control. For example, you can open a custom modal and show any interface to pick or build merge tags or rules.
Merge Tags
You can use this callback function to show custom UI to pick merge tags.
unlayer.registerCallback('mergeTag', function (data, done) {
// data - contains current mergeTagGroup, current mergeTagRule and a list of mergeTags
// done - callback function
// Open custom UI for merge tags here
// Once your user is done choosing a merge tag, call the "done"
// callback function with the new merge tag.
done({
name: 'First Name',
value: '{{first_name}}',
});
});
Merge Tag Groups
You can use this callback function to show custom UI to pick merge tag groups and rules.
unlayer.registerCallback('mergeTagRule', function (data, done) {
// data - contains current mergeTagGroup, current mergeTagRule and a list of mergeTags
// done - callback function
// Open custom UI for merge tag groups here
// Once your user is done choosing a merge tag group and rules,
// call the "done" callback function with the new merge tag group.
// Reset the merge tag group and rules
// done({
// mergeTagGroup: null,
// mergeTagRule: null,
// });
done({
mergeTagGroup: 'products',
mergeTagRule: 'repeat',
});
});
Updated 11 months ago