amp-date-countdown

1.0 0.1

<script async custom-element="amp-date-countdown" src="https://cdn.ampproject.org/v0/amp-date-countdown-0.1.js"></script>

Usage

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

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"
  layout="fixed-height"
  height="50"
>
  <template type="amp-mustache">
    <p class="p1">
{{d}} days, {{h}} hours, {{m}} minutes and {{s}} seconds until
      <a href="https://en.wikipedia.org/wiki/Year_2038_problem">Y2K38</a>.
    </p>
  </template>
</amp-date-countdown>

Returned time parameters

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

Samples of formatted values

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

Attributes

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

end-date

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

timestamp-ms

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

timestamp-seconds

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

timeleft-ms

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:

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

data-count-up (optional)

Include this attribute to reverse the direction of the countdown to count up instead. This is useful to display the time elapsed since a target date in the past. To continue the countdown when the target date is in the past, be sure to include the when-ended attribute with the continue value. If the target date is in the future, amp-date-countdown will display a decrementing (toward 0) negative value.

Events

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

Timeout

When 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.
</h1>

<amp-animation id="hide-timeout-event" layout="nodisplay">
  <script type="application/json">
    {
      "duration": "1s",
      "fill": "both",
      "selector": "#ampdate, #sample",
      "keyframes": {"visibility": "hidden"}
    }
  </script>
</amp-animation>
<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>
    <div>
{{dd}} : {{hh)) : {{mm}} : {{ss}}    </div>
  </template>
</amp-date-countdown>

Renders as:

Validation

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