AMP Roadshow is coming to Atlanta and Berlin!


Display a sequence of backward counting to indicate the time remaining before an event is scheduled to occur.

Required Script<script async custom-element="amp-date-countdown" src=""></script>
Supported Layoutsfill, fixed, fixed-height, flex-item, nodisplay, responsive
ExamplesSee AMP By Example's amp-date-countdown example.


The amp-date-countdown provides countdown time data that you can render in your AMP page. By providing specific attributes in the amp-date-countdown tag, the amp-date-countdown extension returns a list of time parameters, which you can pass to an amp-mustache template for rendering. Refer to the list below for each returned time parameter.


<amp-date-countdown timestamp-seconds="2147483648"
  <template type="amp-mustache">
    <p class="p1">
      {{d}} days, {{h}} hours, {{m}} minutes and {{s}} seconds until
      <a href="">Y2K38</a>.

Returned time parameters

This table lists the format you can specify in your Mustache template:

dday - 0, 1, 2,...12, 13..Infinity
ddday - 00, 01, 02, 03..Infinity
hhour - 0, 1, 2,...12, 13..Infinity
hhhour - 01, 02, 03..Infinity
mminute - 0, 1, 2,...12, 13..Infinity
mmminute - 01, 01, 02, 03..Infinity
ssecond - 0, 1, 2,...12, 13..Infinity
sssecond - 00, 01, 02, 03..Infinity
daysinternationalization string for day or days
hoursinternationalization string for hour or hours
minutesinternationalization string for minute or minutes
secondsinternationalization string for second or seconds

Samples of formatted values

This table provides examples of formatted values specified in a Mustache template, and a sample of what the output:

FormatSample OutputRemarks
{h} {hours} and {m} {minutes} and {s} {seconds}4 hours and 1 minutes and 45 seconds-
{d} {days} {h}:{mm}1 day 5:03-
{d} {days} {h} {hours} {m} {minutes}50 days 5 hours 10 minutes-
{d} {days} {h} {hours} {m} {minutes}20 days 5 hours 10 minutes-
{h} {hours} {m} {minutes}240 hours 10 minutesbiggest-unit='hours'
{d} {days} {h} {hours} {m} {minutes}50 天 5 小时 10 分钟locale='zh-cn'


You must specify at least one of these required attributes: end-date, timeleft-ms, timestamp-ms, timestamp-seconds.


An ISO formatted date to count down to. For example, 2020-06-01T00:00:00+08:00


A POSIX epoch value in milliseconds; assumed to be UTC timezone. For example, timestamp-ms="1521880470000".


A POSIX epoch value in seconds; assumed to be UTC timezone. For example, timestamp-seconds="1521880470".


A value in milliseconds left to be counting down. For example, 48 hours left timeleft-ms="172800000".

offset-seconds (optional)

A positive or negative number that represents the number of seconds to add or subtract from the end-date. For example, offset-seconds="60" adds 60 seconds to the end-date.

when-ended (optional)

Specifies whether to stop the timer when it reaches 0 seconds. The value can be set to stop (default) to indicate the timer to stop at 0 seconds and will not pass the final date or continue to indicate the timer should continue after reaching 0 seconds.

locale (optional)

An internationalization language string for each timer unit. The default value is en (for English). Supported values:

zh-cnChinese Simplified
zh-twChinese Traditional
biggest-unit (optional)

Allows the amp-date-countdown component to calculate the time difference based on the specified biggest-unit value. For example, assume there are 50 days 10 hours left, if the biggest-unit is set to hours, the result displays 1210 hours left.

  • Supported values: days, hours, minutes, seconds
  • Default: days


The amp-date-countdown component exposes the following event that you can use AMP on-syntax to trigger:

timeoutWhen the timer times out. For this action to function, when-ended must be set to stop. You can only run low-trust actions such as amp-animation and amp-video actions when the timer times out. This is to enforce AMP's UX principle of not allowing page content to reflow without explicit user actions.

Example: Demonstrating usage of timeout event

<h1 id="sample">
  When Timer hits 0, will hide the timer itself and hide this message.

<amp-animation id="hide-timeout-event" layout="nodisplay">
<script type="application/json">
        "duration": "1s",
        "fill": "both",
        "selector": "#ampdate, #sample",
        "keyframes": { "visibility": "hidden"}
<amp-date-countdown id="ampdate" end-date="2018-07-17T06:19:40+08:00" on="timeout: hide-timeout-event.start" height="400" width="400" when-ended="stop" locale='en'>
  <template type="amp-mustache">
    <h1>Countdown Clock</h1>
      {{dd}} : {{hh}} : {{mm}} : {{ss}}

Renders as:


See amp-date-countdown rules in the AMP validator specification.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub