Exclusifbêta

Relative Time `<mv-relative-time>`

« Il y a 3 minutes » qui reste à jour tout seul : un vrai <time datetime> avec un texte Intl.RelativeTimeFormat (« maintenant », « dans 2 jours », « hier » selon le jour calendaire, pas sur 24 h), qui passe à une date absolue au-delà d’un seuil, dans la locale du lang le plus proche. Ce que les autres oublient : toutes les instances de la page partagent UN SEUL minuteur qui se réveille exactement quand un texte visible va changer (la minute suivante, l’heure suivante ou minuit, jamais chaque seconde) et dort quand l’onglet est masqué ; la date exacte avec son fuseau horaire s’affiche au survol et au focus clavier et sert de description pour les lecteurs d’écran, tandis que les mises à jour restent silencieuses ; et un export format() pur produit le même texte côté serveur, pour un affichage correct sans JS.

Catégorie	Affichage de données
Type	Web Component (`<mv-relative-time>`)
Statut	bêta
Keywords	exclusive, light, time, date, relative-time, time-ago, intl, i18n, timestamp, ssr

When to use

A feed, comment thread or notification list shows when each item happened as “5 minutes ago”
A table of deploys, orders or tickets needs compact ages that stay current without reloading
Readers must be able to check the exact date and time zone behind an approximate “2 days ago”
Server-rendered pages should print the relative time in HTML and keep it fresh once scripts load

Avoid when

A deadline or event spans time zones and the day shift must be spelled out → use Dateline instead
The value counts down to a launch or promo with ticking seconds
The exact timestamp matters more than its age, as in audit logs or invoices

Installation

node scripts/add.mjs relative-time --out ./src/marvelous

Agent IA avec le serveur MCP de Marvelous UI : install_components({ slugs: ["relative-time"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Fichiers copiés (dépendances comprises) : tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/position.js, components/relative-time/relative-time.js, components/relative-time/relative-time.css.

Utilisation

Démarrage rapide, le balisage minimal qui fonctionne :

<mv-relative-time datetime="2026-09-24T10:00:00Z"></mv-relative-time>

Balisage de référence : partez de celui-ci et personnalisez-le avec les attributs, data-* et les variables CSS :

<div id="mv-relative-time-demo" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,20rem),1fr));gap:1.25rem;width:min(100%,56rem);margin-inline:auto;align-items:start">
  <section aria-labelledby="mv-rt-demo-feed" style="border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);overflow:hidden">
    <h3 id="mv-rt-demo-feed" style="margin:0;padding:.75rem 1rem;border-bottom:1px solid var(--mv-border);font-size:.875rem;font-weight:600">Notifications</h3>
    <ul style="list-style:none;margin:0;padding:.25rem 0;font-size:.875rem;line-height:1.4">
      <li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">AT</span></span><span style="flex:1"><b>Aiko Tanaka</b> commented on <b>Q4 launch checklist</b><br><mv-relative-time data-ago="48" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
      <li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">MR</span></span><span style="flex:1"><b>Mateo Rossi</b> approved invoice INV-0042 for $2,450.00<br><mv-relative-time data-ago="200" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
      <li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">PN</span></span><span style="flex:1"><b>Priya Nair</b> mentioned you in <b>#design</b><br><mv-relative-time data-ago="7900" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
      <li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">LM</span></span><span style="flex:1"><b>Lena Moore</b> shared <b>Brand refresh</b> with you<br><mv-relative-time data-ago="100800" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
      <li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">KB</span></span><span style="flex:1"><b>Kwame Boateng</b> joined the workspace<br><mv-relative-time data-ago="1036800" absolute-after="7d" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
    </ul>
  </section>

  <div style="display:grid;gap:1.25rem">
    <div class="mv-table-wrap">
      <table class="mv-table">
        <caption>Tab to a time to read the exact date and time zone.</caption>
        <thead><tr><th>Environment</th><th>Commit</th><th data-align="end">Deployed</th></tr></thead>
        <tbody>
          <tr><td>Production</td><td><code>a3f9c1e</code></td><td data-align="end"><mv-relative-time tooltip format="short" data-ago="330"></mv-relative-time></td></tr>
          <tr><td>Staging</td><td><code>7d21b04</code></td><td data-align="end"><mv-relative-time tooltip format="short" data-ago="11400"></mv-relative-time></td></tr>
          <tr><td>Scheduled</td><td><code>e58a2f7</code></td><td data-align="end"><mv-relative-time tooltip format="short" data-ago="-180000"></mv-relative-time></td></tr>
        </tbody>
      </table>
    </div>

    <dl style="display:grid;grid-template-columns:auto 1fr;gap:.45rem 1rem;margin:0;padding:.85rem 1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);font-size:.875rem">
      <dt style="color:var(--mv-fg-muted)">long</dt><dd style="margin:0"><mv-relative-time tooltip data-ago="1260"></mv-relative-time></dd>
      <dt style="color:var(--mv-fg-muted)">short</dt><dd style="margin:0"><mv-relative-time tooltip format="short" data-ago="1260"></mv-relative-time></dd>
      <dt style="color:var(--mv-fg-muted)">narrow</dt><dd style="margin:0"><mv-relative-time tooltip format="narrow" data-ago="1260"></mv-relative-time></dd>
      <dt style="color:var(--mv-fg-muted)">lang="fr"</dt><dd style="margin:0" lang="fr"><mv-relative-time tooltip data-ago="172800"></mv-relative-time></dd>
      <dt style="color:var(--mv-fg-muted)">lang="ja"</dt><dd style="margin:0" lang="ja"><mv-relative-time tooltip data-ago="-5400"></mv-relative-time></dd>
      <dt style="color:var(--mv-fg-muted)">Asia/Tokyo</dt><dd style="margin:0"><mv-relative-time tooltip time-zone="Asia/Tokyo" absolute-after="1d" data-ago="259200"></mv-relative-time></dd>
    </dl>
  </div>
</div>
<script type="module">
  // Demo only: anchor every timestamp to "now" so the demo reads the same any day.
  const now = Date.now();
  for (const el of document.querySelectorAll("#mv-relative-time-demo [data-ago]")) el.date = now - Number(el.dataset.ago) * 1000;
</script>

API

Attributes

Name	Type	Default	Description
`datetime`	string		The moment: an ISO 8601 date or date-time (with an offset or Z), or epoch milliseconds. Without it, the datetime of a child `<time>` is used (server-rendered markup).
`format`	long \| short \| narrow	`long`	Intl style: “3 minutes ago”, “3 min. ago”, “3m ago”. Absolute dates use a medium date (long, short) or a numeric date (narrow).
`absolute-after`	span	`30d`	Beyond this distance from now (past or future), show the absolute date instead: a number with s, m, h, d, w, mo or y (“7d”, “12h”), or “never”.
`time-zone`	IANA zone		Time zone for calendar days, the absolute date and the tooltip (default: the viewer’s).
`tooltip`	boolean		Makes the time a tab stop so keyboard and touch users can open the exact date. Hover works without it; leave it off in long lists to avoid a tab stop per row.
`lang (inherited)`	BCP 47		Locale comes from the nearest [lang] ancestor, else the browser’s; changing any lang re-localizes every instance.
`data-mode`	relative \| absolute		Set by the component (for styling).
`data-invalid`	boolean		Set by the component when the date cannot be parsed (the existing text is kept).

Properties

Name	Type	Description
`date`	Date	The moment as a Date; accepts a Date, an ISO string or epoch ms (writes datetime). Can be set before the element is defined.
`locale`	string \| undefined	Resolved locale (read-only).

Methods

Name	Description
`refresh()`	Re-render now (rarely needed: the shared scheduler does it).
`format(date, now?, { locale, format, absoluteAfter, timeZone }?)`	Named export (and static MvRelativeTime.format): pure, server-safe, returns the same text the element shows.
`formatExact(date, { locale, timeZone }?)`	Named export: pure, server-safe exact date, time and zone (“Thursday, September 24, 2026 at 10:00 AM GMT+2”), for a server-side title.

Content structure

Name	Description
`time (optional)`	A server-rendered `<time datetime>` child is adopted and kept (its title, the no-JS fallback, is removed once the tooltip takes over).

CSS classes

Name	Description
`mv-relative-time-text`	The `<time>` element.
`mv-relative-time-tip / -zone`	The exact date bubble (top layer popover) and its time zone chip.

CSS variables

Name	Default	Description
`--mv-relative-time-tip-bg`	`light-dark(var(--mv-gray-950), var(--mv-gray-50))`	Bubble background.
`--mv-relative-time-tip-fg`	`light-dark(var(--mv-gray-50), var(--mv-gray-950))`	Bubble text.
`--mv-relative-time-hint`	`var(--mv-fg-subtle)`	Dotted underline shown on hover (and always with tooltip).

Accessibility

Renders a real <time datetime> in the light DOM, so the text is plain inline content that screen readers read once, in place. There is no live region: minute-by-minute updates change the text silently, and the DOM is only written when the text actually changes. The exact date, time and time zone (“Thursday, September 24, 2026 at 10:00 AM GMT+2”) is the <time>’s accessible description (aria-describedby to the bubble, which is itself aria-hidden so it is never read twice), announced on focus rather than in the reading flow. With tooltip, the time is a tab stop: focus opens the bubble, Escape closes it, blur closes it, and a tap opens it on touch screens. With a mouse (hover: hover and pointer: fine), the bubble opens after a short delay, stays open while the pointer is over it (the text can be selected) and closes on scroll. Visible focus ring; forced colors give the bubble and chip a CanvasText border; opacity-only entry that the reduced-motion duration tokens make instant. Every string comes from Intl (RelativeTimeFormat, DateTimeFormat) in the inherited lang, so there is nothing to translate by hand and no sentence is assembled from fragments. Server-side, format() and formatExact() produce the same text and a title so the page reads correctly without JS.