← 4.6.9 The abbr element – Table of contents – 4.6.11 The code element →

4.6.10 The time element

Categories
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content, but there must be no time element descendants.
Content attributes:
Global attributes
datetime
pubdate
DOM interface:
interface HTMLTimeElement : HTMLElement {
           attribute DOMString dateTime;
           attribute boolean pubDate;
  readonly attribute Date valueAsDate;
};

The time element represents either a time on a 24 hour clock, or a precise date in the proleptic Gregorian calendar, optionally with a time and a time-zone offset. [GREGORIAN]

This element is intended as a way to encode modern dates and times in a machine-readable way so that, for example, user agents can offer to add birthday reminders or scheduled events to the user's calendar.

The time element is not intended for encoding times for which a precise date or time cannot be established. For example, it would be inappropriate for encoding times like "one millisecond after the big bang", "the early part of the Jurassic period", or "a winter around 250 BCE".

For dates before the introduction of the Gregorian calendar, authors are encouraged to not use the time element, or else to be very careful about converting dates and times from the period to the Gregorian calendar. This is complicated by the manner in which the Gregorian calendar was phased in, which occurred at different times in different countries, ranging from partway through the 16th century all the way to early in the 20th.

The pubdate attribute is a boolean attribute. If specified, it indicates that the date and time given by the element is the publication date and time of the nearest ancestor article element, or, if the element has no ancestor article element, of the document as a whole. If the element has a pubdate attribute specified, then the element needs a date. For each article element, there must be no more than one time element with a pubdate attribute whose nearest ancestor is that article element. Furthermore, for each Document, there must be no more than one time element with a pubdate attribute that does not have an ancestor article element.

The datetime attribute, if present, gives the date or time being specified. Otherwise, the date or time is given by the element's contents.

If the element needs a date, and the datetime attribute is present, then the attribute's value must be a valid date string with optional time.

If the element needs a date, but the datetime attribute is not present, then the element's textContent must be a valid date string in content with optional time.

If the element does not need a date, and the datetime attribute is present, then the attribute's value must be a valid date or time string.

If the element does not need a date, but the datetime attribute is not present, then the element's textContent must be a valid date or time string in content.

The date, if any, must be expressed using the Gregorian calendar.

The time element can be used to encode dates, for example in Microformats. The following shows a hypothetical way of encoding an event using a variant on hCalendar that uses the time element:

<div class="vevent">
 <a class="url" href="http://www.web2con.com/">http://www.web2con.com/</a>
  <span class="summary">Web 2.0 Conference</span>:
  <time class="dtstart" datetime="2007-10-05">October 5</time> -
  <time class="dtend" datetime="2007-10-20">19</time>,
  at the <span class="location">Argent Hotel, San Francisco, CA</span>
 </div>

(The end date is encoded as one day after the last date of the event because in the iCalendar format, end dates are exclusive, not inclusive.)

The time element is not necessary for encoding dates or times. In the following snippet, the time is encoded using time, so that it can be restyled (e.g. using XBL2) to match local conventions, while the year is not marked up at all, since marking it up would not be particularly useful, and doing so is thus not allowed.

<p>I usually have a snack at <time>16:00</time>.</p>
<p>I've liked model trains since at least 1983.</p>

Using a styling technology that supports restyling times, the first paragraph from the above snippet could be rendered as follows:

I usually have a snack at 4pm.

Or it could be rendered as follows:

I usually have a snack at 16h00.

The dateTime IDL attribute must reflect the datetime content attribute.

The pubDate IDL attribute must reflect the pubdate content attribute.

time . valueAsDate

Returns a Date object representing the specified date and time.

In the following snippet:

<p>Our first date was <time datetime="2006-09-23">a Saturday</time>.</p>

...the time element's valueAsDate attribute would have the value 1,158,969,600,000ms.

In the following snippet:

<p>Many people get up at <time>08:00</time>.</p>

...the time element's valueAsDate attribute would have the value 28,800,000ms.

In this example, an article's publication date is marked up using time:

<article>
 <h1>Small tasks</h1>
 <footer>Published <time pubdate>2009-08-30</time>.</footer>
 <p>I put a bike bell on his bike.</p>
</article>

Here is another way that could be marked up. In this example, legacy user agents would say "today", while newer user agents would render the time in a locale-specific manner based on the value of the attribute.

<article>
 <h1>Small tasks</h1>
 <footer>Published <time pubdate datetime="2009-08-30">today</time>.</footer>
 <p>I put a bike bell on his bike.</p>
</article>

Here is the same thing but with the time included only. Because the element is empty, legacy user agents will not show anything useful; user agents that implement this specification, on the other hand, would show the date and time in a locale-specific manner.

<article>
 <h1>Small tasks</h1>
 <footer>Published <time pubdate datetime="2009-08-30T07:13Z"></time>.</footer>
 <p>I put a bike bell on his bike.</p>
</article>