time

The time element represents a specific period in time, providing a machine-readable datetime value while displaying a human-readable format to users.

Description

The <time> element represents a specific moment or range of time. It encodes dates and times in a machine-readable format via the datetime attribute while displaying human-friendly text. This enables browsers, search engines, and assistive technologies to parse and utilize temporal data.

When to Use

  • Publication dates — Blog posts, articles, news
  • Event times — Meetings, appointments, concerts
  • Deadlines — Due dates, expiration dates
  • Historical dates — Birthdays, anniversaries, milestones
  • Durations — Length of videos, podcasts, events

When Not to Use

  • For vague time references ("Last week", "Soon") with no specific datetime
  • For non-Gregorian dates that can't be represented in ISO 8601
  • For machine-readable non-temporal values — use <data>

Basic Usage

Standard time element with tabular numeric font for consistent digit widths.

Relative Variant

Muted, smaller text for relative time displays. Typically updated by JavaScript to show how long ago something occurred.

Datetime Variant

Monospace font for technical datetime displays, such as log entries or API timestamps.

Badge Variant

Pill-style badge for dates that need to stand out, such as event dates, release versions, or deadlines. Add the data-badge attribute to any <time> element.

Formats and Patterns

Dates, times, combined formats, and ISO 8601 durations.

Auto-Formatting (data-format-date)

VB provides locale-aware date formatting via the data-format-date attribute. Like <data>'s data-format-number, the visible text serves as a no-JS fallback and is replaced with formatted output on init.

Attribute ValueOutput (en-US)
data-format-date (empty)Feb 9, 2026 (medium)
data-format-date="short"2/9/26
data-format-date="long"February 9, 2026
data-format-date="full"Monday, February 9, 2026
data-format-date="relative"2 days ago

Add data-format-time for time display (short, medium, long, full). Override locale per-element with data-locale. See the i18n guide for locale resolution.

Contextual Usage

Time elements work naturally in article metadata, event listings, and other contextual patterns.

datetime Attribute Formats

The datetime attribute uses ISO 8601 format:

Format Example Represents
YYYY 2026 Year
YYYY-MM 2026-01 Month
YYYY-MM-DD 2026-01-15 Date
HH:MM 14:30 Time
YYYY-MM-DDTHH:MM 2026-01-15T14:30 Date and time
YYYY-MM-DDTHH:MM:SS 2026-01-15T14:30:00 With seconds
...Z 2026-01-15T14:30:00Z UTC timezone
...+HH:MM 2026-01-15T14:30:00+05:30 With timezone offset
PTXHXMXS PT2H30M Duration

Variant Summary

Variant Selector Use Case
Default time Standard dates with tabular numerals
Relative time.relative Muted "2 days ago" displays
Datetime time.datetime Technical timestamps in monospace
Badge time[data-badge] Pill-style emphasis for key dates

CSS Properties

Accessibility

  • Screen readers read the visible text content (the human-readable part)
  • Machine parsing — the datetime attribute enables assistive technologies to parse dates accurately
  • Timezone clarity — include timezone information when relevant to avoid ambiguity
  • Relative times — update dynamically via JavaScript or provide the actual date as fallback
  • <data> — Machine-readable values that aren't dates (has data-format-number counterpart)
  • <del> / <ins> — Use datetime attribute for edit timestamps
  • <small> — Often paired with time for date caveats
  • Internationalization — Locale resolution for date formatting
↑