How to use dynamic text replacement

Dynamic Text Replacement (DTR) is a powerful feature to add personalization to your popups.

It allows you to create messages featuring the data you've collected from the visitor. That includes information they've submitted through the form, their location, products in their cart, current date, and so on.

Template displaying visitor’s name using dynamic text

In this guide, we’ll show you how to add dynamic text to widgets, cover the platform’s built-in variable options, and share some advanced DTR use cases. To navigate the sections of this article, use the shortcut menu below.

Adding a variable to a widget

To display dynamic text on widgets, you need to add so-called “variables” to the text of the widget. Variables should appear in the text of widgets in the following format:


To add a variable, select the necessary text element on the widget, click the {var} button, and select a variable from the list:

The {var} button and variable set

It’s possible to add variables to the following elements of your widget:

  • title
  • description
  • note
  • field labels
  • field placeholder text
  • field default value
  • button URL
  • follow-up email text
  • follow-up email subject
  • follow-up email preview

Depending on where on the widget you're adding a variable, it can be displayed within a block or in curly brackets.

For example, when you add a variable to the title, description, and note fields, it will be displayed as a block:

A variable displayed as a block in the Description field

To edit this variable, click on its block and apply your changes to the Expression field (we'll talk more about expressions in a few moments):

Editing a variable in the Description field

When you add a variable to a simple text field — the placeholder text field, the default value field, or the button URL field, for example — the variable will be displayed as simple text in curly brackets:

A variable in curly brackets in the button URL field

You can edit these variables as you would edit any other piece of text.

💡 It’s possible to add a default value that will be displayed if the variable is empty (i.e. there is no data in the system to show for that variable). In that case, you should express the variable in the following format:

{{var | default}}

For example, the following expression allows you to display the text “Hi there!” instead of “Hi (name)!” if there is no data to display for the {{name}} variable:

{{name | there}}

This is what the visitor will see if their name is not in the database:

Template displaying alternative text “Hi there!”

In the upcoming sections, we’ll discuss variable subsets from the built-in {var} menu in detail. Then, we’ll proceed to introduce some advanced options.

Form data

Form variables allow you to use the information a visitor has previously submitted through the form.

For example, if you are collecting names on the first page of a form, you can display the name entered by the visitor on the submission success page of the same form:

Adding a Name variable to the widget

The Form subset of variables features the IDs of all fields in the form:

The Field ID and Form variables

To display the data collected by a specific field, select its ID from the {var} menu when adding it to the text.


The variables from the Geo subset allow you to display the visitor’s location on the widget.

For example, you can display your visitors’ current city on a free shipping bar. To do that, choose the City variable from the list:

Adding a City variable to the widget

Other options from the Geo variable subset include:

  • Country
  • Country code
  • Region
  • State code
  • Postal code

💡 We recommend expressing location-based variables in the following format:

{{$city | your door}}

This way, if the visitor is hiding their location, the popup will display a message like this one:

Popup template with “Free shipping to your door” message


The variables from the Device subset let you display personalized messages based on the visitor’s device properties and settings.

For example, let’s say you want to display your visitor’s operating system on the widget, and open a different link via a button click depending on the visitor’s OS.

Example of widget with OS variable in place

To set up this scenario, choose the OS variable from the menu and add it to the widget’s text:

Adding an OS variable to the widget

Then, to set up the button to open the link corresponding to the visitor’s OS, proceed as follows:

  1. Open the settings of your action button by clicking on it
  2. Click + Add action and choose Open URL from the dropdown menu
  3. Paste the JavaScript expression below into the URL field:
{{!= $os == 'iOS' ? '' : ''}}

Adding the JS expression to the URL field in the action button settings

Now Android users will be redirected to Google Play, and iOS users will be taken to the App Store.

To learn more about using JavaScript expressions, check out the section dedicated to them.

Here are other variables you can use in the text of your widget from the Device subset:

  • Language displays the language set from the visitor’s browser.
  • Browser displays the name of the browser the visitor is using.
  • Device displays the visitor’s device name, e.g. iPhone.
  • Device type displays the visitor’s device type, e.g. Desktop, Mobile, or Tablet.


Date variables allow you to show the current date based on the visitor’s system settings.

For example, you may want to display the current month as the ending date of a promo to add urgency to your offer:

Example of popup featuring a Month variable in the description text

To set this up, switch to the Date subset of variables in the menu, and proceed to select Month:

Adding a Month variable to the widget

Below are the other variables in the Date subset:

  • Date displays the current date, e.g. 02/23/2023.
  • Weekday displays the current day of the week, e.g. Thursday.
  • Day displays the day of the month, e.g. 23.


The Developer variables allow you to use custom API parameters to display the information you have in your database about the visitor.

For example, you can display the visitor’s name, subscription status, and their personal discount, as in the example below:

Example of popup featuring variables from the Developer subset

To set up custom variables like these ones, select API parameter from the Developer variable subset in the menu:

Using API to display visitor’s subscription status and personal discount

💡 You can set a default alternative text to display in case there is no value to show for one of the Developer variables, like the visitor’s name, for example:

{{name | there}}

This is the message your visitors will see if their name is not in your database:

Displaying default text on the widget

You will find detailed instructions on how to use the Getsitecontrol API feature in this guide.


The UTM variables allow you to display the source the visitor is coming from, the marketing channel, the campaign, or specific keywords.

For example, you can use a UTM Source variable to display the source a visitor is coming from and greet them with a personalized message:

Example of popup displaying a UTM Source variable

To set this up, select UTM Source from the UTM subset of variables in the menu:

Adding a UTM source variable to the widget

This subset includes variables for all other UTM tags as well, namely:

  • UTM Medium
  • UTM Campaign
  • UTM Content
  • UTM Term


If you’re on Shopify, you’ll find an extra subset of variables labeled Shopify in your menu.

The Shopify variable subset

In the following sections, we’ll discuss popular use cases for the variables in this category.

Displaying the customer’s name

If a customer has logged in to your store while browsing your products, you can display their name on your popups:

Popup displaying the customer’s name

To make this happen, choose Customer name from the Shopify subset and add the variable to the text of your popup:

Adding a Customer name variable to the popup

Offering free shipping on the currently viewed item

To give your customers that extra nudge to purchase the item they are checking, you can display a free shipping offer on that item.

Popup displaying the product’s vendor

In the text of the popup, you can display the name of the specific item on the page ( Variant title ); the product category it belongs to, e.g. “Accessories” ( Product Type ); or the vendor ( Product vendor ):

Adding a Product vendor variable to the popup

Displaying how much is left to spend to get free shipping

To increase the average order value on your store, you can tempt your customers with free shipping if they spend more than X amount of money.

Popup displaying the amount of money left to spend to get free shipping

Setting this up will require you to use the Cart total price variable within a simple JavaScript expression. Let’s take a look at the steps.

Let’s say you want to offer free shipping to customers who spend more than $100.

First, choose Cart total price from the {var} menu:

Adding a Cart total price variable to the widget

Click the {{$cartTotalPrice}} block in the rich text editor and copy the following expression from the suggestions menu:

Copying and pasting an expression from the variable suggestion menu

Paste {{= CURRENCY(100 - $cartTotalPrice)}} into the Expression field and save the changes.

This expression will show visitors how much more they have to spend to get free shipping. The value will be preceded by the symbol of the currency of your store.

Find more DTR use cases in our blog post. And to learn more about JavaScript expressions, check out the dedicated paragraph in this guide.

Advanced options

In this section you’ll find advanced DTR options that allow for deeper text customization.

Adding variables to the Open URL action

The DTR feature allows you to add variables to the button URL, and pass along data collected by the widget.

For example, you can pass emails collected by a form field to the ‘Open URL’ action.

To set this up, open the action button settings and add the ‘Open URL’ action. Next, enter the chosen URL in the corresponding field in the following format:{{email}}

Adding an Email variable to the Open URL action

Upon button click, the popup will now open the URL containing the submitted email.

It’s also possible to pass variables into an Open URL action with the help of API. Here is the method you should use:

gsc('params', {url: ''})

After you’ve added this script to your site, add {{!url}} to the URL field in the action settings. The exclamation character at the beginning prevents URL encoding.

Adding true to the URL field in the action settings

If necessary, you can pass along a query string containing several GET parameters. Here is the method to achieve that:

gsc('params', {query: 'price=10&quantity=2'})

Make sure to add {{!query}} to the URL field in the Open URL action settings:

Adding true to the URL field in the action settings

The final URL should look like the following:{{!query}}

Using JavaScript expressions

You can use JavaScript expressions in the rich text editor of your widget to create personalized messages for your visitors. The following is the correct format to add JS expressions to the widget’s text:


expression represents any valid JavaScript expression whose result is displayed to the visitor.

To prevent HTML escaping in the expressions (which happens by default in the widget editor), add an exclamation mark at the beginning of the expression:

{{!= expression }}

In an expression, you can use different variables.

For example, you can use the expression below to display a specific customer status depending on how much the customer has spent:

{{= totalSpent>1000 ? 'Premium' : 'Basic' }}

Here is an example of a popup featuring the above-mentioned expression:

The result of the expression (above) on a widget

Or, you can use the expression below to format the visitor’s name and add a title:

{{= 'MR. ' + name.toUpperCase() }}

Here is the result of the expression on a popup:

The result of the expression (above) on a widget

For more examples of text personalization, check out our dedicated blog post.

If you have any questions or thoughts, feel free to contact us, we’ll be happy to help you implement your idea!

Browse by category