Timer
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.
| Property | Default 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%" } |
| textAlign | center |
| 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).
| Property | Type | Notes |
|---|---|---|
countdownUrl | string | Placeholder GIF shown before the timer is rendered |
endTime | string | ISO date-time, e.g. 2030-01-01T00:00:00 |
backgroundColor | string | Hex or rgb(a) color |
labelColor | string | Hex or rgb(a) color |
digitColor | string | Hex or rgb(a) color |
labelFontFamily | string | One of the supported fonts below (case-insensitive) |
digitFontFamily | string | One of the supported fonts below (case-insensitive) |
labelFontSize | number | |
digitFontSize | number | |
timezone | string | IANA timezone, e.g. America/Los_Angeles |
locale | string | null | null uses the editor's locale |
showLabels | boolean |
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.