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.

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:

With Time

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

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:

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:

Common Use Cases

Activity Feeds

Show when events happened in a list:

Alice commented

Bob pushed a commit

Carol opened an issue

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.

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
↑