--- title: "Countdown Timer GIF for Emails" slug: "create-a-countdown-timer-block" updated: 2026-08-26T14:36:46Z published: 2026-08-26T14:36:46Z canonical: "docs.mapp.com/create-a-countdown-timer-block" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Countdown Timer GIF for Emails ## Overview This component is intended for advanced email template customization. The Countdown Timer GIF feature allows users to embed customizable animated countdown timers into emails or webpages. The countdown is delivered as a GIF and supports a wide range of parameters for appearance, layout, behavior, and localization. --- ## Customization Parameters | Parameter | Required | Description | Example | | --- | --- | --- | --- | | `date` | Yes | Target datetime in `YYYY-MM-DD/H:mm:ss` format. | `2025-11-10/4:00:00` | | `width` | No | GIF width in pixels. Default: `400`, maximum: `800`. | `300` | | `height` | No | GIF height in pixels. Default: `400`, maximum: `800`. | `300` | | `frames` | No | Number of animation frames. Default: `60`, maximum: `120`. | `60` | | `color` | No | Text color (hex, no `#`). Default: `ffffff`. | `000000` | | `bg` | No | Background color (hex, no `#`). Default: `000000`. | `ffffff` | | `font` | No | Font family. Any font from the service's Google Fonts catalog works by name. Fonts outside the catalog need their full Google Fonts URL on first use. Default: `Courier New`. | `Montserrat` | | `fontsize` | No | Font size in pixels for both numbers and captions. Default: `32`. | `40` | | `numbersFontSize` | No | Font size for the numbers. Requires `gifStyle=custom` and overrides `fontsize`. Default: `32`. | `48` | | `captionsFontSize` | No | Font size for the captions. Requires `gifStyle=custom` and overrides `fontsize`. Default: `32`. | `20` | | `gifStyle` | No | `default` or `custom`. The custom style unlocks the parameters that control numbers and captions separately. Default: `default`. | `custom` | | `captions` | No | Show or hide the time unit labels (`true` or `false`). Default: `true`. | `false` | | `dateFormat` | No | Time units to display, as short codes or full words. Default: `d,h,m,s`. | `d,h,m` | | `lang` | No | Caption language: `en`, `de`, `es`, `fr`, `it`. Default: `en`. | `it` | | `divider` | No | Character shown between the time units. `&`, `#` and `+` are not supported. Default: a space. | `/` | | `offset` | No | Extra pixel space between the individual digits inside one number, for example between the "1" and the "2" in "12". Default: `0`. | `10` | | `dividerSpacing` | No | Extra pixel space between a number and the divider next to it. Requires `gifStyle=custom`. Does not scale with `width`. Default: `0`. | `12` | | `customMessage` | No | Message shown once the countdown has ended, up to 99 characters. Default: `00d 00h 00m 00s`. | `Sale ended!` | | `transparentBg` | No | Render the background transparent (`true` or `false`), ignoring `bg`. Default: `false`. | `true` | | `tz` | No | Timezone identifier used for the countdown calculation. Default: the server timezone. | `Europe/Rome` | | `bgImage` | No | URL of a background image. Overrides `bg`. | `https://example.com/bg.jpg` | | `bgImageMode` | No | How the background image is drawn: `cover`, `contain`, `stretch` or `center`. Default: `cover`, which is also the only mode confirmed to render consistently across email clients. | `cover` | | `bgImageScale` | No | Scale multiplier for the background image, applied with `bgImageMode=center`. Default: `1`. | `0.8` | --- ## Parameter Details ### Fonts Google Fonts can be applied in two ways: - **By name** — pass the font name, for example `font=Montserrat`. This works on the first request for every font in the service's Google Fonts catalog, and needs no further setup. - **By URL** — for a font that is not in the catalog, pass its full Google Fonts URL once, for example `font=https://fonts.googleapis.com/css2?family=SomeFont`. From then on, the font name alone works as well. > [!NOTE] > Note > > A font added by URL is not guaranteed to stay available after a service update or restart. If you need a font permanently, ask Mapp Support to add it to the catalog instead. If `font` is omitted, or the value is not a recognized font name or Google Fonts URL, the default font `Courier New` is used. ### Digit and Divider Spacing Two separate parameters control the horizontal spacing inside the countdown: - `offset` sets the space between the individual digits inside one number, for example between the "1" and the "2" in "12". - `dividerSpacing` sets the space between a number and the divider next to it, for example between "12" and "/". It stays the same no matter how wide you make the timer, so a wider countdown area does not stretch these gaps on its own. `dividerSpacing` requires `gifStyle=custom`. Example: `?date=2026-10-29/4:00:00&gifStyle=custom&dividerSpacing=12` ### Captions Captions are the time unit labels below the numbers. Hide them with `captions=false`. When the captions are hidden, the numbers are re-centered automatically to fill the space the labels used to occupy. You do not need to compensate for this with `height` or any other parameter. To translate the captions, use `lang` with a supported language code. Do not use `dateFormat` at the same time, because it prevents the language change from working. ### Transparent Background Set `transparentBg=true` to render the timer without a background color, so it blends into the surrounding email background. GIF supports only fully opaque or fully transparent pixels, with no partial transparency. To keep the digit edges as clean as possible, the service renders each frame at a higher internal resolution and smooths it down before encoding the GIF. This happens automatically. > [!NOTE] > Note > > There is no need to request an inflated `width` and `height` and scale the result down in the email. The service already handles this internally. ### Background Image Use `bgImage` to place an image behind the countdown instead of a solid color. The image URL must be HTTPS, and URL encoding is recommended. `bgImageMode` controls how the image is drawn. `cover` is the default and the only mode confirmed to render consistently across email clients. `contain`, `stretch` and `center` remain available, so use another mode only if you have a specific reason to. Example: `?date=2026-10-29/4:00:00&width=800&height=500&bgImage=https%3A%2F%2Fpicsum.photos%2F800%2F600.jpg` --- ## Rendering Considerations - The GIF is rendered server-side and cached for performance. - Empty parameters are ignored by the backend, and default values are used. - The GIF is fully compatible with major email clients (no JavaScript required). --- ## Production-Ready Template Code ```vbscript-html #set ($date = ${tplPlaceholder.element('"inline":"false","name":"Date","id":"80980b91-bde6-4abf-8c20-a383831bef81","type":"text","value":"2025-11-10/4:00:00","group":"GIF Settings"')}) #set ($width = ${tplPlaceholder.element('"inline":"false","name":"Width","id":"80980b91-bde6-4abf-8c20-a383831bef82","type":"number","value":"300","group":"GIF Settings"')}) #set ($height = ${tplPlaceholder.element('"inline":"false","name":"Height","id":"80980b91-bde6-4abf-8c20-a383831bef83","type":"number","value":"300","group":"GIF Settings"')}) #set ($frames = ${tplPlaceholder.element('"inline":"false","name":"Frames","id":"80980b91-bde6-4abf-8c20-a383831bef84","type":"number","value":"60","group":"GIF Settings"')}) #set ($fontColor = ${tplPlaceholder.element('"inline":"false","name":"Color","id":"80980b91-bde6-4abf-8c20-a383831bef85","type":"text","value":"000000","group":"GIF Settings"')}) #set ($background = ${tplPlaceholder.element('"inline":"false","name":"Background color","id":"80980b91-bde6-4abf-8c20-a383831bef86","type":"text","value":"ffffff","group":"GIF Settings"')}) #set ($font = ${tplPlaceholder.element('"inline":"false","name":"Font","id":"80980b91-bde6-4abf-8c20-a383831bef87","type":"text","value":"Montserrat","group":"GIF Settings"')}) #set ($fontSize = ${tplPlaceholder.element('"inline":"false","name":"Font size","id":"80980b91-bde6-4abf-8c20-a383831bef88","type":"text","value":"16","group":"GIF Settings"')}) #set ($divider = ${tplPlaceholder.element('"inline":"false","name":"Divider","id":"80980b91-bde6-4abf-8c20-a383831bef89","type":"text","value":"/","group":"GIF Settings"')}) #set ($lang = ${tplPlaceholder.element('"inline":"false","name":"Lang","id":"80980b91-bde6-4abf-8c20-a383831bef90","type":"text","value":"it","group":"GIF Settings"')}) #set ($customMsg = ${tplPlaceholder.element('"inline":"false","name":"Custom message","id":"80980b91-bde6-4abf-8c20-a383831bef91","type":"text","value":"","group":"GIF Settings"')}) #set ($offset = ${tplPlaceholder.element('"inline":"false","name":"Offset","id":"80980b91-bde6-4abf-8c20-a383831bef92","type":"number","value":"0","group":"GIF Settings"')}) #set ($gifStyle = ${tplPlaceholder.element('"inline":"false","name":"GIF Style","id":"80980b91-bde6-4abf-8c20-a383831bef93","type":"text","value":"default","group":"GIF Settings"')}) #set ($numbersFontSize = ${tplPlaceholder.element('"inline":"false","name":"Numbers font size","id":"80980b91-bde6-4abf-8c20-a383831bef94","type":"text","value":"32","group":"GIF Settings"')}) #set ($captionsFontSize = ${tplPlaceholder.element('"inline":"false","name":"Captions font size","id":"80980b91-bde6-4abf-8c20-a383831bef95","type":"text","value":"32","group":"GIF Settings"')}) #set ($captions = ${tplPlaceholder.element('"inline":"false","name":"Captions","id":"80980b91-bde6-4abf-8c20-a383831bef96","type":"text","value":"true","group":"GIF Settings"')}) #set ($dateFormat = ${tplPlaceholder.element('"inline":"false","name":"Date Format","id":"80980b91-bde6-4abf-8c20-a383831bef97","type":"text","value":"","group":"GIF Settings"')}) #set ($transparentBg = ${tplPlaceholder.element('"inline":"false","name":"Transparent background","id":"80980b91-bde6-4abf-8c20-a383831bef98","type":"text","value":"false","group":"GIF Settings"')}) #set ($tz = ${tplPlaceholder.element('"inline":"false","name":"Timezone","id":"80980b91-bde6-4abf-8c20-a383831bef99","type":"text","value":"Europe/Rome","group":"GIF Settings"')}) #set ($bgImage = ${tplPlaceholder.element('"inline":"false","name":"Background image","id":"80980b91-bde6-4abf-8c20-a383831bef9A","type":"text","value":"","group":"GIF Settings"')}) #set ($bgImageMode = ${tplPlaceholder.element('"inline":"false","name":"Background image mode","id":"80980b91-bde6-4abf-8c20-a383831bef9B","type":"text","value":"cover","group":"GIF Settings"')}) #set ($bgImageScale = ${tplPlaceholder.element('"inline":"false","name":"Background image scale","id":"80980b91-bde6-4abf-8c20-a383831bef9C","type":"text","value":"1","group":"GIF Settings"')}) #set ($dividerSpacing = ${tplPlaceholder.element('"inline":"false","name":"Divider spacing","id":"80980b91-bde6-4abf-8c20-a383831bef9D","type":"number","value":"0","group":"GIF Settings"')})
``` --- ## Best Practices - Set the `date` parameter to a valid future datetime to ensure the countdown is visible. - Use `gifStyle=custom` when applying separate font sizes to numbers and captions, or when adjusting `dividerSpacing`. - Avoid using characters like `&`, `+` or `#` in the `divider` parameter. - To make a number easier to read, increase `offset`. To open up the space around the dividers, increase `dividerSpacing` instead. - For localized captions, use the `lang` parameter and avoid `dateFormat` at the same time. - Keep `bgImageMode=cover` for background images unless you have tested another mode in your target email clients. - Once you add the block to the email message, you can customize it using the **Details** panel in the **Compose Email Message** window. --- ## Known Limitations - Maximum frame count: `120`. - Maximum width and height: `800` pixels. - Fonts must come from Google Fonts. Fonts in the service catalog work by name, any other Google Font needs its full Google Fonts URL on first use, and everything else falls back to `Courier New`. - `dividerSpacing` only takes effect together with `gifStyle=custom`. - Background images must be hosted on secure (HTTPS) URLs. - Avoid extremely large font sizes if using small dimensions, because the text is not resized to fit. ## Related - [25 – Countdown](/25-countdown.md)