Exclusivobeta

Countdown `<mv-countdown>`

Contagem regressiva até uma data para lançamentos, promoções, webinars e eventos: dias, horas, minutos e segundos (configuráveis) em algarismos tabulares com rótulos no plural correto via Intl, nas variantes simples, card ou compacta. Os detalhes em que os outros erram: cada tique é recalculado a partir do relógio real e agendado no próximo limite real de segundo (sem deriva, sem intervalo que se acumula), a renderização pausa enquanto a aba está oculta ou o timer está fora da tela e ressincroniza na volta, passar o mouse ou focar mostra a data-alvo no horário local do visitante (“Wed, Oct 7, 9:01 AM your time”), nunca mostra números negativos: ao chegar a zero, troca para o seu conteúdo “ended” em slot e dispara mv-end exatamente uma vez, mesmo quando a página é aberta depois do fim, e os leitores de tela recebem um role=timer discreto cujo nome é atualizado uma vez por minuto em vez de a cada segundo.

Categoria	Exibição de dados
Tipo	Web Component (`<mv-countdown>`)
Status	beta
Keywords	exclusive, light, countdown, timer, launch, sale, event, webinar, time-zone, intl

When to use

A launch, product drop or event page needs a live countdown to a fixed date and time
A sale or promo banner should show a compact time left that turns into an ended message on its own
A webinar or live stream page should swap the timer for a Join button when it starts
Visitors in other time zones need to see when the moment falls in their own local time

Avoid when

The moment should read as relative text like “in 2 days” or “3 minutes ago” rather than a ticking timer → use Relative Time instead
A deadline must be read as a date across two time zones with the day shift spelled out → use Dateline instead
A prompt waits a few seconds and then takes a default choice if nobody answers → use Timed Choice instead

Instalação

node scripts/add.mjs countdown --out ./src/marvelous

Agente de IA com o servidor MCP do Marvelous UI: install_components({ slugs: ["countdown"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Arquivos copiados (dependências incluídas): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/observe.js, components/countdown/countdown.js, components/countdown/countdown.css.

Uso

Início rápido, a menor marcação que funciona:

<mv-countdown to="2026-10-07T09:01:00+02:00"></mv-countdown>

Marcação de referência, para usar como ponto de partida e personalizar com atributos, data-* e variáveis CSS:

<div id="mv-countdown-demo" style="display:grid;gap:1rem;width:100%;max-width:560px">
  <div style="display:flex;flex-wrap:wrap;align-items:center;justify-content:center;gap:.4rem .75rem;padding:.6rem 1rem;border-radius:var(--mv-radius-lg);background:var(--mv-accent-subtle);color:var(--mv-fg);font-size:.875rem">
    <strong>Summer sale: 30% off annual plans</strong>
    <span style="color:var(--mv-fg-muted)">Ends in <mv-countdown data-variant="compact" data-offset="187200" to="2026-10-01T18:00:00-04:00" label="Summer sale">Oct 1, 6:00 PM EDT<template slot="ended">The sale has ended</template></mv-countdown></span>
  </div>

  <section style="display:grid;justify-items:center;gap:1rem;padding:1.75rem 1rem 1.5rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-xl);background:var(--mv-surface);box-shadow:var(--mv-shadow-md);text-align:center">
    <div style="display:grid;gap:.3rem">
      <span style="font-size:.75rem;font-weight:600;letter-spacing:.08em;text-transform:uppercase;color:var(--mv-accent-fg)">Lumen 2.0</span>
      <strong style="font-size:1.25rem">Doors open in</strong>
    </div>
    <mv-countdown data-variant="card" data-offset="1123265" to="2026-10-07T09:01:00+02:00" label="Launch">Wednesday, October 7, 9:01 AM CEST</mv-countdown>
    <span style="font-size:.8rem;color:var(--mv-fg-subtle)">Hover or focus the timer to see the time in your time zone.</span>
  </section>

  <div style="display:flex;flex-wrap:wrap;align-items:center;justify-content:space-between;gap:.75rem;padding:.9rem 1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-bg-subtle)">
    <div style="display:grid;gap:.15rem">
      <strong style="font-size:.9rem">Webinar: Designing for 12 languages</strong>
      <span style="font-size:.8rem;color:var(--mv-fg-muted)">with Aiko Tanaka and Mateo Ruiz</span>
    </div>
    <mv-countdown id="mv-countdown-demo-live" units="m s" data-offset="9" to="2026-10-01T16:00:00Z" label="Webinar" style="--mv-countdown-size:1.5em">
      <template slot="ended">
        <span style="width:.5rem;height:.5rem;border-radius:50%;background:var(--mv-danger);box-shadow:0 0 0 3px color-mix(in oklch,var(--mv-danger) 25%,transparent)"></span>
        <span style="font-size:.8rem;font-weight:600">Live now</span>
        <a class="mv-button" data-size="sm" href="#">Join webinar</a>
      </template>
    </mv-countdown>
  </div>

  <div style="display:flex;justify-content:center">
    <button class="mv-button" data-variant="ghost" data-size="sm" id="mv-countdown-demo-replay">Replay webinar start</button>
  </div>
</div>

<script type="module">
  // Demo only: aim each timer a fixed number of seconds ahead so it always runs.
  const root = document.getElementById("mv-countdown-demo");
  const aim = (el) => { el.to = new Date(Date.now() + Number(el.dataset.offset) * 1000).toISOString(); };
  root.querySelectorAll("mv-countdown[data-offset]").forEach(aim);
  const live = document.getElementById("mv-countdown-demo-live");
  document.getElementById("mv-countdown-demo-replay").addEventListener("click", () => aim(live));
</script>

API

Attributes

Name	Tipo	Default	Description
`to`	ISO 8601 date-time		Target moment, ideally with an offset or Z (2026-10-07T09:01:00+02:00) so every visitor counts down to the same instant. Missing or invalid: dashes and data-state="idle".
`units`	string	`d h m s`	Units to show, largest first, separated by spaces or commas (d, h, m, s, or days, hours…). The largest shown unit absorbs the rest (units="h m" → 49 hours 05 minutes); without seconds the smallest unit rounds up so zero only appears at the end. Leading zero units drop out while more than two remain.
`label`	string		What is being counted down to, prefixed to the accessible name (“Launch: 12 days, 4 hours, 5 minutes remaining”).
`locale`	BCP 47 tag	`nearest lang, else en-US`	Locale for digits, unit labels, the local-time tip and the accessible name.
`data-variant`	card \| compact	`(plain)`	Plain: large digits with labels and colons. Card: one tile per unit. Compact: one line of text (2d 04h 05m 06s) for bars, buttons and sentences.
`data-state`	idle \| running \| ended		Set by the component (for styling).
`data-swapped`	boolean		Set by the component while the ended content replaces the digits.

Properties

Name	Tipo	Description
`to / units / label / locale`	string	Mirror the attributes.
`strings`	object	Override default texts: remaining (“{time} remaining”), soon (“Less than a minute remaining”), ended (“Ended”), labelled (“{label}: {status}”), local (“{date} your time”).
`remaining`	number	Milliseconds left, 0 once ended, NaN without a valid target (read-only).
`ended`	boolean	True once the target has passed (read-only).

Events

Name	Description
`mv-end`	Fired once per target when it reaches zero, or one task after the upgrade when the page opens after the end; detail = { to: Date, late: boolean }. Cancelable: preventDefault() keeps the zeroed timer instead of swapping in the ended content.

Content structure

Name	Description
`(text)`	Fallback shown before JavaScript runs (SSR, no JS), e.g. the date written out; replaced by the live display on upgrade.
`ended`	`<template slot="ended">` or any [slot=ended] child: shown instead of the digits at zero (a message, a Join or Shop button).

CSS classes

Name	Description
`mv-countdown-units / -unit / -value / -label`	Generated digits (aria-hidden; data-unit = d \| h \| m \| s).
`mv-countdown-tip`	Local-time tooltip (role=tooltip, linked with aria-describedby).
`mv-countdown-ended`	Added to the ended content.

CSS variables

Name	Default	Description
`--mv-countdown-size`	`2.25em / 2em card / 1em compact`	Digit size.
`--mv-countdown-gap`	`0.8 × size / var(--mv-space-2) card / 0.4em compact`	Space between units.
`--mv-countdown-color`	`var(--mv-fg)`	Digit color.
`--mv-countdown-separator`	`var(--mv-fg-subtle)`	Colon color (plain variant).

Accessibility

The host is a role=timer with aria-live=off, so nothing is announced by itself; the visible digits are aria-hidden and the accessible name is a full sentence built with Intl.NumberFormat units and Intl.ListFormat, rewritten at most once a minute (“Launch: 2 days, 4 hours, 5 minutes remaining”, then “Less than a minute remaining”, then “Ended”). The timer is focusable (tabindex=0 unless you set one) and describes itself with the local-time tooltip (role=tooltip, aria-describedby), shown on hover, keyboard focus or tap focus, hoverable and dismissed with Escape (WCAG 1.4.13). When ended content is swapped in, the timer role, name and tab stop are removed so your message or button reads as normal content. All texts come from strings and Intl in the chosen locale (plural-correct units, local digits). Tabular digits keep the width steady; no continuous motion, the ended content fades in (instant under reduced motion or data-motion=reduce). Forced colors: tooltip and tiles get system borders, focus shows a system outline. SSR-safe (no window access at import); the fallback text is readable without JavaScript.