HTML5 time Element

time Element Basics
- The time Element in the HTML5 Specification
The Proleptic Gregorian Calendar
Date Format
Durations
The pubdate Attribute
Semantic Uses of time

Jakob Jenkov
Last update: 2014-06-15

The HTML5 time element is used to semantically mark up date and time in an HTML5 page.

time Element Basics

The time element contains the date in two versions. One date version in a machine readable format, and one version in a human readable format. Here is a time element example:

<time datetime="2012-05-01">May 1st 2012</time>

The machine readable version of the date is written in the datetime attribute. The human readable version is written between the start and end tags, as the body of the time element.

If you just want to use the machine readable version of the date, you can put the machine readable date version inside the body of the time element, and leave out the datetime attribute. Here is an example:

<time>2012-05-01</time>

The time Element in the HTML5 Specification

In late 2011 the time element was removed from the HTML5 specification, but it was added back, with a few updates. As of may 2012 the time element is alive and kicking.

The Proleptic Gregorian Calendar

The time element must contain a positive date in the proleptic Gregorian calendar. This means that no dates can be earlier than the year 0000 in the Gregorian (christian) calendar.

Date Format

The date format of the time elements must be in one of the following formats:

YYYY-MM-DDTHH:MM:SS.SSS+ZHZM
YYYY-MM-DDTHH:MM:SS.SSS-ZHZM
YYYY-WXX

The meaning of the codes used in the format above is:

Letter Code	Meaning
YYYY	The year specified using 4 digits, e.g. 2012
MM	The month specified using 2 digits, e.g. 09 or 12. The month must be between 01 and 12.
WXX	The week of the year specified using 2 digits, e.g. 01 or 31. The week must be between 01 and 53.
DD	The day specified using 2 digits, e.g. 01 or 31. The month must be between 01 and 31.
T	The T signals that this date also contains a time part listed after the T. It is also legal to use a space instead of a T.
HH	The hours specified using 2 digits. The hours go from 00 to 23.
MM	The minutes specified using 2 digits. The minutes go from 00 to 59.
SS	The seconds specified using 2 digits. The seconds go from 00 to 59.
SSS	The milliseconds specified using 3 digits. The milliseconds go from 000 to 999.
-ZHZM	The time zone offset from UTC (Coordinated Universal Time), specified using a + or - and then the offset in hours and minutes using 4 digits total (HHMM).
+ZHZM	The time zone offset from UTC (Coordinated Universal Time), specified using a + or - and then the offset in hours and minutes using 4 digits total (HHMM).

Some parts of this format are optional. For instance, you don't need the time part. If you do have a time part, the seconds and millisecond parts are optional. If you do have a time part, however, you must also have a time zone part.

Here are a list of legal example date and time formats:

Format	Example
YYYY	2012
YYYY-MM	2012-05
YYYY-MM-DD	2012-05-30
YYYY-WXX	2012-W49
MM-DD	05-30
YYYY-MM-DDTHH:MM-ZHZM	2012-05-30T23:59-0500
YYYY-MM-DDTHH:MM:SS-ZHZM	2012-05-30T23:59:59-0500
YYYY-MM-DDTHH:MM:SS.SSS+ZHZM	2012-05-30T23:59:59:999+0200
YYYY-MM-DDTHH:MM:SS.SSS-ZHZM	2012-05-30T23:59:59:999-0500

Durations

It is possible to specify durations using the time element, instead of precise dates. This is done by prefixing the time with a P, then writing a number of time units, and finally a letter specifying the time unit. Here is an example:

<time datetime="P1D">

This example specifies a duration of 1 day (D).

The duration units you can use are:

Unit	Description
D	Days
H	Hours
M	Minutes
S	Seconds

You cannot specify months, since a month is not a fixed amount of time (seconds). The length of a month in seconds depends on which month you are talking about.

It is allowed to separate the parts of the duration with spaces (for readability), like this:

<time datetime="P 1 D">

If you use the T after the P you can specify more precise durations. For instance:

<time datetime="PT12H 34M 59S">

This example specifies a duration of 12 hours, 34 minutes and 59 seconds.

Notice how it is allowed to separate the various components of the duration with spaces. You could also write the above duration like this:

<time datetime="PT 12H 34M 59S">
<time datetime="PT12H34M59S">

The pubdate Attribute

The time elements pubdate attribute indicates whether the given time element is the publication date of the enclosing article element, or the whole body element.

Note: At the time of writing there is a proposal to drop the pubdate attribute. It is not dropped yet, though.

Here is an example:

<time datetime="2012-05-01" pubdate>May 1st 2012</time>

Notice that you do not need to se a specific true/false value for the pubdate attribute. If the attribute is present as shown above, the time element is considered a publication date.

Here is an example with a time element embedded in an article element:

<article>

    <p>
        This is the last time a meteor hit earth.
    </p>

    <p>
        <time datetime="2012-05-01" pubdate>May 1st 2012</time>
    </p>

</article>

There are no rules about whether the time element should be enclosed in a p element, or be a direct child of the article element.

Semantic Uses of time

The time element can be used by browsers and web crawlers of search engines to deduct the semantic meaning of the HTML that is being displayed. For instance, a browser may be able to detect dates and ask if you want that date added to a calendar, or formatted differently. A web crawler may be able to use the time element to analyze when a given article was posted, to detect how often a web site changes.

There will probably be more semantic uses for the time element in the future.

Next: HTML5 File API

Tweet
	Jakob Jenkov