Skip to main content
Version: Latest

Timer

Paid Feature

This feature is only available in paid plans. Learn More

Timer is a built-in tool used to create countdown timers. This tool create a countdown GIF image to run a realtime countdown. It is supported in both display modes: email and web pages.

Enable / Disable​

Timer tool is a premium tool. If you have it in your subscription, It's enabled by default but you can choose to disable it.

unlayer.init({
tools: {
timer: {
enabled: false,
},
},
});

Default Values​

Timer tool comes with the following default values. You can choose to change any of these.

PropertyDefault Value
countdown{ countdownUrl: "https://cdn.tools.unlayer.com/countdown/countdown.gif", endTime: "", backgroundColor: "#FFFFFF", labelColor: "#A3A3A3", labelFontFamily: "Open Sans", labelFontSize: 16, digitColor: "#404040", digitFontFamily: "Open Sans", digitFontSize: 40, timezone: "America/Los_Angeles", locale: null, showLabels: true }
width{ autoWidth: true, width: "100%" }
textAligncenter
altText"" (empty: the end date is used, see Alternate Text)
action{ name: "web", values: { href: "", target: "_blank" } }

Here are a few examples on how to change these default values.

Countdown Properties​

You can change any of the default countdown properties such as labels, language, fonts, timezone, etc.

Each property expects a specific type. Only locale accepts null; for every other property, omit it to keep its default rather than passing null (an omitted property always falls back to its built-in default).

PropertyTypeNotes
countdownUrlstringPlaceholder GIF shown before the timer is rendered
endTimestringISO date-time, e.g. 2030-01-01T00:00:00
backgroundColorstringHex or rgb(a) color
labelColorstringHex or rgb(a) color
digitColorstringHex or rgb(a) color
labelFontFamilystringOne of the supported fonts below (case-insensitive)
digitFontFamilystringOne of the supported fonts below (case-insensitive)
labelFontSizenumber
digitFontSizenumber
timezonestringIANA timezone, e.g. America/Los_Angeles
localestring | nullnull uses the editor's locale
showLabelsboolean

labelFontFamily and digitFontFamily accept one of the following names (matched case-insensitively, so arial resolves to Arial): Arial, Arial Black, Book Antiqua, Comic Sans MS, Courier New, Georgia, Helvetica, Impact, Open Sans, Times New Roman. An unrecognized name falls back to Open Sans.

unlayer.init({
tools: {
timer: {
properties: {
countdown: {
value: {
countdownUrl: `https://cdn.tools.unlayer.com/countdown/countdown.gif`,
endTime: '',
backgroundColor: '#000000',
labelColor: '#FFFFFF',
labelFontFamily: 'Open Sans',
labelFontSize: 28,
digitColor: '#FFFFFF',
digitFontFamily: 'Open Sans',
digitFontSize: 75,
timezone: 'America/Los_Angeles',
locale: null,
showLabels: false,
},
},
},
},
},
});

Layout​

By default, the layout is set to horizontal but you can change it to vertical.

unlayer.init({
tools: {
timer: {
properties: {
layout: {
value: 'vertical',
},
},
},
},
});

Width​

By default, countdown GIF image is added with auto width turned on. You can change it.

unlayer.init({
tools: {
timer: {
properties: {
width: {
value: {
autoWidth: false,
width: '50%',
},
},
},
},
},
});

Alternate Text​

The countdown is a GIF, so recipients whose email client blocks remote images see the alternate text instead. When the alternate text is empty (or still the former default Countdown), the exported image uses the countdown's end date in its configured timezone and language, for example Oct 7, 2026, 11:05 AM PDT, so the deadline is still readable when the timer itself is not shown. Set your own text to replace it.

unlayer.init({
tools: {
timer: {
properties: {
altText: {
value: 'Countdown Timer',
},
},
},
},
});

The exported image also declares the countdown's size, so clients that support it keep the design's layout while the GIF loads or when images are blocked.