data-format-date

Locale-aware date and relative time formatting via data attributes.

Overview

The data-format-date attribute enhances native <time> elements by replacing their text content with a locale-aware formatted date. Supports both absolute date formats and auto-refreshing relative time strings.

<time datetime="2026-02-09" data-format-date>Feb 9, 2026</time>

How It Works

  1. Reads the datetime attribute from the <time> element
  2. Stores the original text content as a title attribute (visible on hover)
  3. For absolute styles: formats using Intl.DateTimeFormat with the specified dateStyle
  4. For "relative": formats using Intl.RelativeTimeFormat and starts adaptive auto-refresh

The formatting uses the user's browser locale by default.

Attributes

Attribute Type Description
data-format-date string Date style: "" / "medium" (default), "short", "long", "full", "relative".
datetime string Standard HTML datetime attribute. Must be a valid date string (ISO 8601 recommended).
data-format-time string Optional time style: "short", "medium", "long", "full". Ignored when "relative".
data-locale string Optional locale override (e.g., "de-DE"). Defaults to browser locale.
title string Set automatically to the original text content (unless already set). Provides hover tooltip.
data-format-date-init boolean Set automatically to prevent double-binding. Do not set manually.

Absolute Date Styles

Date styles map directly to Intl.DateTimeFormat's dateStyle option:

Default (medium):

Short:

Long:

Full:

<!-- Medium (default) --> <time datetime="2026-02-09" data-format-date>Feb 9, 2026</time> <!-- Short --> <time datetime="2026-02-09" data-format-date="short">2/9/26</time> <!-- Long --> <time datetime="2026-02-09" data-format-date="long">February 9, 2026</time> <!-- Full --> <time datetime="2026-02-09" data-format-date="full">Sunday, February 9, 2026</time>

With Time

Add data-format-time to include the time component:

<time datetime="2026-02-09T14:30:00" data-format-date="long" data-format-time="short"> February 9, 2026, 2:30 PM </time>

Relative Time

Use data-format-date="relative" for auto-refreshing relative time strings like "3 hours ago" or "in 2 days".

5 minutes ago:

2 hours ago:

Yesterday:

Last week:

In 1 hour:

<time datetime="2026-02-09T10:00:00Z" data-format-date="relative">February 9, 2026</time>

Auto-Refresh Intervals

Relative times update automatically on an adaptive schedule:

Age of timestamp Refresh interval
< 1 hour Every 60 seconds
< 24 hours Every 5 minutes
> 24 hours Every hour

Intervals are automatically cleared when elements are removed from the DOM (tracked via MutationObserver).

Locale Override

Use data-locale to force a specific locale for formatting:

German:

Japanese:

<time datetime="2026-02-09" data-format-date="long" data-locale="de-DE">9. Februar 2026</time> <time datetime="2026-02-09" data-format-date="long" data-locale="ja-JP">2026年2月9日</time>

Common Use Cases

Activity Feeds

Show when events happened in a list:

Alice commented

Bob pushed a commit

Carol opened an issue

<ul> <li> Alice commented <time datetime="..." data-format-date="relative">5 minutes ago</time> </li> <li> Bob pushed a commit <time datetime="..." data-format-date="relative">2 hours ago</time> </li> </ul>

Content Metadata

Display article or post timestamps:

Getting Started with Vanilla Breeze

Published

Dynamic Elements

Elements added to the DOM after page load are automatically enhanced via a MutationObserver. No manual initialization is needed.

// Dynamically added elements are auto-enhanced via MutationObserver const time = document.createElement('time'); time.setAttribute('datetime', new Date().toISOString()); time.dataset.formatDate = 'relative'; time.textContent = 'just now'; document.body.appendChild(time); // time is enhanced automatically — no manual init needed

Progressive Enhancement

The <time> element's original text serves as a fallback when JavaScript is unavailable. Users always see a readable date, with formatting layered on top.

<time datetime="2026-02-09" data-format-date>Feb 9, 2026</time>

Accessibility

  • The original human-readable date is preserved as a title attribute, accessible on hover
  • For relative times, the cursor: help style hints that additional information is available
  • The semantic <time> element with datetime attribute provides machine-readable dates for assistive technology
  • Falls back to the original text content when JavaScript is unavailable
  • No wrapper element — the <time> is the enhanced element, keeping the accessibility tree clean