Countdown Timer

Link to article: Countdown Timer.

.croqstyle__documentation :is(h1, h2) {
  font-family: Inter, sans-serif;
  font-weight: bold;
}
.croqstyle__documentation h2 { margin-top: 2rem }
.croqstyle__documentation h3 { margin-top: 2.5rem }

.croqstyle__documentation #toc,
.croqstyle__description {
  border: thin solid #ddd;
  padding: 1em;
  background-color: transparent;
}
td { vertical-align: top; }
.options table.wiki-content-table td { border: none; padding: 0.7em 1em; }

```
height: 3rem
```

:scp-wiki:component:croqstyle [info]

```
croqstyle__documentation
```
```
croqstyle__description
```
```
html-block-iframe
```
```
code
```
```
terminal
```
```
options
```
```
blockquote
```
```
code
```
```
countdown
```
```
timer
```
```
timer--active
```
```
timer
```
```
timer--elapsed
```
```
countdown-wrapper
```
```
countdown
```
```
timer
```
```
timer--active
```
```
timer-pause
```
```
timer
```
```
timer--elapsed
```

[[iftags +component]]

[[include :scp-wiki:component:croqstyle -=- ]]

[[module CSS]]
.croqstyle__documentation :is(h1, h2) {
  font-family: Inter, sans-serif;
  font-weight: bold;
}
.croqstyle__documentation h2 { margin-top: 2rem }
.croqstyle__documentation h3 { margin-top: 2.5rem }

.croqstyle__documentation #toc,
.croqstyle__description {
  border: thin solid #ddd;
  padding: 1em;
  background-color: transparent;
}
td { vertical-align: top; }
.options table.wiki-content-table td { border: none; padding: 0.7em 1em; }
[[/module]]

[[div class="croqstyle__documentation"]]
[[div class="croqstyle__description"]]
This is a component that displays a countdown timer. Give it a timestamp and it'll count down to it.

++ Demo

[[embed]]
<iframe src="https://scp-sandbox-3.wdfiles.com/local--html/demo%3Acountdown-timer/2f51a331ec18aba963d57dd2a1cea2f7065d0298-686842511317953009/scp-sandbox-3.wikidot.com/" allowtransparency="true" class="html-block-iframe" style="height: 3rem"></iframe>
[[/embed]]

More live examples: https://scp-sandbox-3.wikidot.com/demo:countdown-timer

++ Usage

Put this in your page:

[[div class="code terminal"]]
##var(--c-keyword)|[[####var(--c-builtin)|include## ##var(--c-symbol)|:scp-wiki:component:countdown##
##var(--c-keyword)||## ##var(--c-builtin)|timestamp####var(--c-keyword)| = ####var(--c-string)|1752897600##
##var(--c-keyword)||## ##var(--c-builtin)|format####var(--c-keyword)| = ####var(--c-string)|DDd HH:MM:SS##
##var(--c-keyword)||## ##var(--c-builtin)|text_when_elapsed####var(--c-keyword)| = ####var(--c-string)|Timer ended.##
##var(--c-keyword)||## ##var(--c-builtin)|css####var(--c-keyword)| = ##
##var(--c-string)|.countdown {##
##var(--c-string)|@@  @@font-size: 2em;##
##var(--c-string)|@@  @@font-weight: bold;##
##var(--c-string)|@@  @@text-align: center;##
##var(--c-string)|}##
##var(--c-keyword)|]]##
[[/div]]

The following parameters are supported. To get the default value of an optional parameter, don't add the parameter at all.

[[div class="options"]]
|| **timestamp** || The timestamp to count down to, as a UNIX timestamp. _
Or, a comma-separated list of UNIX timestamps. _
Or, a formula (see below). ||
|| **//format//** _
//(Optional)// || The output format of the timer. Custom HTML is OK. _
The tokens {{WW}}, {{DD}}, {{HH}}, {{MM}} and {{SS}} will be replaced with the number of weeks/days/hours/minutes/seconds in the countdown. _
//Default value: HH:MM:SS// ||
|| **//text_when_elapsed//** _
//(Optional)// || Text to display when the timer has elapsed once it's finished counting down. Custom HTML is OK. _
//Default value: 00:00:00 (your format with all values set to 0)// ||
|| **//css//** _
//(Optional)// || CSS to style the interior of the component's iframe. To style the exterior, use a standard CSS module. _
 _
E.g. for use on a page with a dark theme, try {{.countdown { color: white }}} ||
[[/div]]

After a countdown timer has permanently elapsed, the content is pretty much static and the countdown functionality is no longer needed. When convenient, you should remove the countdown timer from the page and replace it with normal content.

If you need a hand, give [[*user Croquembouche]] (that's me) a shout.

+++ Picking a timestamp

This component uses UNIX timestamps, which is the number of seconds since 1970 in the UTC timezone. A given UNIX timestamp elapses at the exact same time for everyone, no matter where in the world they are - there's no need to hassle with timezones and localisation.

E.g.:

* {{1767225600}} - count down to 2026, midnight UTC
* {{1863561600}} - count down to 2029-01-20, midnight UTC

To get the UNIX timestamp for the end time you have in mind, there are plenty of free resources available, such as https://www.unixtimestamp.com/.

If you //do// need timezone localisation, we have a component for that: [[[component:tz|]]]

+++ Timestamp list

You can pass timestamps as a comma-separated list. The component will pick the first one that isn't in the past.

The timer will elapse when the current time reaches that timestamp. It will not automatically move on to the next one in the list, it will show the {{text_when_elapsed}} content. The next time the page is loaded it will start counting down to the next one in the list.

+++ Timestamp formula

If you want an adaptive countdown that e.g. repeats forever, or depends on when the page was loaded, you provide a formula instead of a hardcoded timestamp.

In a formula, the letter 't' is replaced with the timestamp when the page was loaded, and the rest is passed to Javascript's calculator. The output must be the next timestamp to count down to.

E.g.:

* {{t + 60}} - count down to 60 seconds from when the page was loaded
* {{t - (t % 60) + 60}} - count down to the next full minute. (That's the current timestamp, minus it mod 60 to round it down to a full minute. That results in a timestamp that's in the past, so add 60 to push it to the future)
* {{t - (t % 3600) + 3600}} - count down to the next full hour
* {{Math.floor(t / 86400) * 86400 + 86400}} - count down to midnight UTC
* {{Math.floor(t / 86400) * 86400 + 86400 + 21600}} - count down to 6 AM UTC

Unless you're a genius it will probably take you a sec to parse how the maths there works. FYI I am not a genius and the above equations also describe how long it takes for me to forget how they work.

[[collapsible show="+ wait, what? how does that work?" hide="- here's how that works"]]
[[div class="blockquote"]]
Take the {{t - (t % 60) + 60}} example, which counts down to the next full mibnute.

Say the current time is 09:41:33 AM - the current timestamp is therefore 1776069693. We therefore want our timer to count down 27 seconds. How do we come up with that formula?

* {{t}} = 1776069693, aka 09:41:33 AM.
* {{t % 60}} = 1776069693 mod 60, which is the remainder after fitting as many 60's into 1776069693 as you can. You can fit 29,601,161 60's into 1776069693, which leaves a remainder of 33. Therefore, {{t % 60}} = 33.
* {{t - (t % 60)}} = 1776069693 - 33 = 1776069660. That's a timestamp - 09:41:00 AM. We successfully shaved off the 33 seconds, and rounded the time down to the previous minute.
* 09:41:00 AM is earlier than the current time, 09:41:33 AM, so that would cause the timer to show as elapsed immediately. We'll add 60 seconds to move up by exactly one minute: {{t - (t % 60) + 60}} = 1776069720, aka 09:42:00 AM.
* 09:42:00 AM is 27 seconds from now (09:41:33 AM), so the timer will last 27 seconds and then elapse.

Note that this process happens in, like, a microsecond, so we don't need to worry about now becoming not-now-anymore.
[[/div]]
[[/collapsible]]

++ CSS structure

For the purposes of CSS styling, this is the structure of the contents of the iframe. Check the page source for all the details.

[[div class="code"]]
@@  <div class="countdown">@@
@@    <span class="timer timer--active">00:00:00</span>@@

@@    <!-- Only shows when the timer has elapsed -->@@
@@    <span class="timer timer--elapsed">Timer ended.</span>@@
@@  </div>@@
[[/div]]

The iframe itself is wrapped in a div with class {{.countdown-wrapper}}.

+++ Advanced CSS

You can use CSS to make the page react when a timer elapses. The selector {{.countdown-wrapper:has(iframe[style*=".01px"])}} will match an elapsed countdown. There's an example of this on the [https://scp-sandbox-3.wikidot.com/demo:countdown-timer demos page].

++ Accessibility

This countdown timer is built with accessibility best practices in mind. Consider reading the below before you use this component, so that you don't mess up my perfect implementation by doing stupid stuff.

**TL;DR:** Avoid using this component to remove content while the reader is still reading, as that's a non-accessible experience.

ARIA properties:

* The timer uses [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role ARIA role "timer"], which denotes it as a timer to screen reader users but doesn't keep repeating it when the timer changes every second.
* When a timer finishes counting down, it uses [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live aria-live="polite"] to wait for a quiet moment and then politely announce your {{text_when_elapsed}} to screen reader users - but it only does this if the text isn't e.g. "00:00:00".

[https://www.w3.org/TR/WCAG22/ WCAG 2.2] compliance:

* [https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html SC 2.2.1 Timing Adjustable] (Level A): If this timer is being used to synchronise with a real-life event (e.g. to the end of a contest, or to a sequel being posted), this requirement is waived. If this timer is being used to artificially create a delay before the reader can continue reading, that fails the guideline in letter but not in spirit, as the intent is to give the user enough time to complete an action, and they can always just carry on reading once the timer has expired. If you use this timer to //remove// content from the reader before they might have a chance to finish, that's a violation of the guideline.
* [https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html SC 2.2.2 Pause, Stop, Hide] (Level A): On hover or focus, a button is revealed that pauses the timer on click or keyboard interaction.
* [https://www.w3.org/WAI/WCAG22/Understanding/no-timing.html SC 2.2.3 No Timing] (Level AAA): So long as this timer is not being used to //remove// content from the user, this is a pass. Fail if this component is used to set a time //limit// as opposed to simply counting down to something.
* [https://www.w3.org/WAI/WCAG22/Understanding/three-flashes.html SC 2.3.2 Three Flashes] (Level AAA): Even with large gaudy fonts, the timer flashes at most once per second, which is below the maximum threshold (three flashes per second).

[[/div]]
[[/div]]

[[/iftags]]

[[div_ class="countdown-wrapper"]]
[[html]]
<head>
<script>
  const inputs = {
    timestamp: `{$timestamp}`,
    format: `{$format}`,
  }
</script>

<link href="https://d3g0gp89917ko0.cloudfront.net/v--edac79f846ba/common--theme/base/css/style.css" rel="stylesheet">
<link href="https://scp-wiki.wikidot.com/local--code/component%3Atheme/1" rel="stylesheet">

<script src="https://interwiki.scpwiki.com/resizeIframe.js" defer></script>
<script>
  window.resize = () => {}
</script>

<style>
  .countdown {
    padding-block: 0.2em;
    font-variant-numeric: tabular-nums;
  }
  .timer--elapsed, .countdown--elapsed .timer--active {
    display: none;
  }
  .countdown--elapsed .timer--elapsed {
    display: inline;
  }

  .timer-pause {
    mask-size: contain;
    font-size: 0;
    height: 1rem;
    width: 1rem;
    border: none;
    vertical-align: middle;
    color: inherit !important;
    background-color: currentColor !important;
    mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24'%3E%3Cpath fill='%23000' d='M2 5.27L3.28 4L20 20.72L18.73 22l-3.08-3.08c-1.15.38-2.37.58-3.65.58c-5 0-9.27-3.11-11-7.5c.69-1.76 1.79-3.31 3.19-4.54zM12 9a3 3 0 0 1 3 3a3 3 0 0 1-.17 1L11 9.17A3 3 0 0 1 12 9m0-4.5c5 0 9.27 3.11 11 7.5a11.8 11.8 0 0 1-4 5.19l-1.42-1.43A9.86 9.86 0 0 0 20.82 12A9.82 9.82 0 0 0 12 6.5c-1.09 0-2.16.18-3.16.5L7.3 5.47c1.44-.62 3.03-.97 4.7-.97M3.18 12A9.82 9.82 0 0 0 12 17.5c.69 0 1.37-.07 2-.21L11.72 15A3.064 3.064 0 0 1 9 12.28L5.6 8.87c-.99.85-1.82 1.91-2.42 3.13'/%3E%3C/svg%3E");
    opacity: 0;
    margin-right: -1rem;
  }
  .countdown--paused .timer-pause {
    mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24'%3E%3Cpath fill='%23000' d='M12 9a3 3 0 0 1 3 3a3 3 0 0 1-3 3a3 3 0 0 1-3-3a3 3 0 0 1 3-3m0-4.5c5 0 9.27 3.11 11 7.5c-1.73 4.39-6 7.5-11 7.5S2.73 16.39 1 12c1.73-4.39 6-7.5 11-7.5M3.18 12a9.821 9.821 0 0 0 17.64 0a9.821 9.821 0 0 0-17.64 0'/%3E%3C/svg%3E");
  }
  .countdown--paused .timer--active {
    opacity: 0.5;
  }
  :where(.countdown:hover, .countdown:focus-within, .countdown--paused) .timer-pause {
    opacity: 1;
  }
</style>
<style>{$css}</style>
</head>

<body>
<div class="countdown">
  <span class="timer timer--active" role="timer" id="timer"></span><button class="timer-pause" type="button" aria-controls="timer" title="Hide timer. The countdown will still end at the correct time.">Hide</button>

  <!-- Only shows when the timer has elapsed -->
  <span class="timer timer--elapsed">{$text_when_elapsed}</span>
</div>
</body>

<script>
function log() {
  console.log("component:countdown:", ...arguments)
}

let interval = 0
let paused = false
let elapsed = false
const timeTokens = { WW: 604800, DD: 86400, HH: 3600, MM: 60, SS: 1 }
const emptyDelta = { WW: 0, DD: 0, HH: 0, MM: 0, SS: 0 }
const defaultFormatString = "HH:MM:SS"

function getTargetTime(inputString, now) {
  // If the input is literally a timestamp, return it directly
  if (!Number.isNaN(Number(inputString))) {
    log("Received specific timestamp", inputString)
    return Number(inputString)
  }

  // If it's a list of timestamps, get the next one
  if (inputString.includes(",")) {
    log("Received timestamp list", inputString)
    const timestamps = inputString.split(",").map(Number)
    for (const timestamp of timestamps) {
      if (!Number.isNaN(timestamp) && timestamp > now) {
        return timestamp
      }
    }
  }

  // If it's a formula, parse it
  if (inputString.includes("t")) {
    log("Received timestamp formula", inputString)
    const expression = inputString.replaceAll("t", String(now))
    log("Evaluating", expression)
    let result
    try {
      result = eval?.(expression)
      log("Evaluated to", result, `(${typeof result})`)
      if (!Number.isNaN(Number(result))) return Number(result)
    } catch (error) {
      log("Evaluation failed with error", error)
      throw error
    }
  }

  log("Failed to get a valid future timestamp")
  return 0
}

function parseDelta(delta, formatString) {
  const result = {...emptyDelta}
  for (const [token, tokenSize] of Object.entries(timeTokens)) {
    if (formatString.includes(token)) {
      const tokenCount = Math.floor(delta / tokenSize)
      delta = delta - tokenSize * tokenCount
      result[token] = tokenCount
    }
  }
  return result
}

function formatDelta(delta, formatString) {
  let formatted = formatString
  for (let [token, tokenCount] of Object.entries(delta)) {
    if (["HH", "MM", "SS"].includes(token)) {
      tokenCount = String(tokenCount).padStart(2, "0")
    }
    formatted = formatted.replace(token, tokenCount)
  }
  return formatted
}

function processCountdown(target) {
  const now = Math.floor(Date.now() / 1000)
  const deltaSecs = target - now

  const formatString = inputs.format === "{"+"$format}"
    ? defaultFormatString
    : inputs.format

  if (deltaSecs <= 0) {
    setCountdownDone(formatString)
    return true
  }

  if (paused) return false

  const delta = parseDelta(deltaSecs, formatString)
  const formattedDelta = formatDelta(delta, formatString)
  document.querySelector(".countdown .timer").innerHTML = formattedDelta

  window.resize(document.body.scrollHeight)
  return false
}

function setCountdownDone(formatString) {
  elapsed = true
  clearInterval(interval)
  document.querySelector(".timer-pause").remove()
  const countdownEl = document.querySelector(".countdown")
  const doneEl = countdownEl.querySelector(".timer--elapsed")
  if (doneEl.textContent === "{"+"$text_when_elapsed}") {
    doneEl.textContent = formatDelta({...emptyDelta}, formatString)
  } else {
    countdownEl.setAttribute("aria-live", "polite")
    countdownEl.setAttribute("aria-atomic", "true")
  }
  document.querySelector(".timer").remove()
  countdownEl.classList.add("countdown--elapsed")

  window.resize(document.body.scrollHeight)
}

function reimplementResize() {
  // [[html]] iframes come with their own resize script
  // Remove this so that we can use our own to control the value
  document.querySelectorAll(
    "script[src*='common--javascript/html-block-iframe.js']"
  ).forEach(s => s.remove())

  addEventListener("load", () => {
    document.querySelectorAll(
      "iframe[src*='common--javascript/resize-iframe.html']"
    ).forEach(i => i.remove())

    const resizeRaw = window.resizeIframe.createResizeIframe(
      document.referrer,
      // Extract last 2 segments of [[html]] pseudopath
      location.href.replace(/^.*\/(.*\/.*\/)/, "/$1"),
      100,
    )
    window.resize = val => {
      resizeRaw(val + (elapsed ? 0.01 : 0))
    }
    window.resize(document.body.scrollHeight)
  })
}

addEventListener("DOMContentLoaded", () => {
  reimplementResize()

  const now = Math.floor(Date.now() / 1000)
  const target = getTargetTime(inputs.timestamp, now)
  const alreadyEnded = processCountdown(target)
  if (alreadyEnded) return

  interval = setInterval(() => processCountdown(target), 1000)

  document.querySelector(".timer-pause")?.addEventListener("click", () => {
    paused = !paused
    document.querySelector(".countdown")?.classList.toggle("countdown--paused", paused)
    processCountdown(target)
  })
})
</script>
[[/html]]
[[/div]]

[!-- --]

Countdown Timer

Module Styles

Inline Styles

Includes

CSS Classes

Page Source