time element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Description

The time element represents dates, times, time-zone offsets and durations. Additionally, a machine-readable version of the element's contents can be provided in the datetime attribute.

Although the presence of the datetime attribute isn't required, it can be useful to give a version of the element's contents easier to handle for script, that doesn't require altering them.

If the time element is declared without the datetime attribute, it cannot have any element descendants.

Possible variants of the machine-readable version that the datetime attribute can provide must follow any of the syntaxes described below.

Months

A month syntax is composed by:

  1. A year greater than zero, consisting of at least four digits.
  2. A minus sign or hypen character ("-").
  3. A month between 1 and 12, consisting of two digits.

Example

<time>2014-07</time>
<time>0512-12</time>

Dates

A date syntax is composed by:

  1. A valid month syntax representing year and month.
  2. A minus sign or hypen character ("-").
  3. A two digits day between 1 and the numbers of days for the previously specified month and year.

Example

<time>2014-07-05</time>
<time>1920-12-31</time>

Yearless dates

A yearless date syntax is composed by:

  1. Optionally, two minus signs or hypens ("-").
  2. A month between 1 and 12, consisting of two digits.
  3. A minus sign or hypen character ("-").
  4. A two digits day between 1 and the numbers of days for the previously specified month in a leap year.

Example

<time>02-29</time>
<time>--10-20</time>

Times

A time syntax is composed by:

  1. Two digits representing an hour between 0 and 23.
  2. A colon character (":").
  3. A two digits minute between 0 and 59.
  4. The following information, which is optional if the number of seconds is zero:
    1. A colon character (":").
    2. Two digits representing the integer part of the seconds, between 0 and 59.
    3. The following information, which is optional if the number of seconds is an integer:
      1. A period or full stop character (".").
      2. The fractional part of the seconds composed by one, two or three digits.

Example

<time>23:59:59.999</time>
<time>10:20:00.000</time>
<time>10:20</time>
<time>10:20:00</time>

Local dates and times

A local date and time syntax is composed by:

  1. A valid date syntax representing year, month and day.
  2. A capital letter T or a space character (" ").
  3. A valid time syntax representing the time. Note: in a normalised local date and time string, only the shortest variant can be used in this point (for example, omitting the number of seconds when it's zero).

Example

<time>2014-10-29 23:59:59.999</time>
<time>1999-12-03 10:20:00.000</time>
<time>2000-12-15T10:20</time>
<time>1823-01-02T10:53:12.2</time>

A normalized local date and time syntax is composed by:

  1. A valid date syntax representing year, month and day.
  2. A capital letter T.
  3. A valid time syntax representing the time. Note: in a normalised local date and time string, only the shortest variant can be used in this point (for example, omitting the number of seconds when it's zero).

Example

<time>2001-01-01T00:00</time>
<time>1984-01-01T00:25:32.25</time>

Local dates and times are useful when authors need to specify a moment in time that's not dependent of the time zone information. Examples of use could be documents directed to audiences from a particular time zone, or events that happen at the same time in any time zone, like the beginning of a new day that occurs always at 00:00 hs.

Time zones

A time zone syntax is composed by:

  1. A minus sign or hypen character ("-") if the offset is negative, and a plus sign character ("-") otherwise.
  2. Two digits representing an hour between 0 and 23.
  3. Optionally, a colon character (":").
  4. A two digits minute between 0 and 59.

Example

<time>-12:00</time>
<time>+00:00</time>
<time>+00:30</time>
<time>-1100</time>

This format allows a range of time zones wider than what's currently used in practice. The reason for this excess is to improve adaptability to future time zones changes, as they are subject to political decisions.

Global dates and times

A global date and time syntax is composed by:

  1. A valid date syntax representing year, month and day.
  2. A capital letter T or a space character (" ").
  3. A valid time syntax representing the time.
  4. A valid time zone syntax representing the time-zone offset.

Example

<time>2014-01-14 00:12-03:00</time>
<time>2014-05-16T20:12+00:30</time>
<time>2201-08-20 03:04:22.5-5:00</time>
<time>2000-04-01T02:00:00.00+4:00</time>

For a global date and time syntax to be a normalised forced-UTC global date and time string, it must be composed by:

  1. A valid date syntax representing year, month and day, converted to UTC time zone.
  2. A capital letter T.
  3. A valid time syntax representing the time, converted to UTC time zone and in its shortest variant (for example, omitting the number of seconds when it's zero).
  4. A capital letter Z.

Example

<time>2014-02-03T22:00Z</time>
<time>2010-01-01T00:00:00.001Z</time>
<time>2050-01-03T23:59Z</time>
<time>1980-12-23T00:05Z</time>

Weeks

A week syntax is composed by:

  1. A week-year (a bit different to regular years, delimited by the limits of weeks) greater than zero, consisting of at least four digits.
  2. A minus sign or hypen character ("-").
  3. A capital letter W.
  4. Two digits representing the week number, between 1 and the maximum number of weeks present in this particular year, being either 52 or 53.

A week in this model is considered as a seven-day period starting on a Monday. The first week of a year is the one that has the first Thursday.

Example

<time>1986-W03</time>
<time>2014-W52</time>

Durations

A duration syntax is composed by:

  1. A capital letter P.
  2. Any of the following duration time components, in this order:
    1. At least one digit representing the number of days, followed by a capital letter D.
    2. Optionally a capital letter T followed by any of the duration time components described below:
      1. One or more digits representing the number of hours, followed by a capital letter H.
      2. One or more digits representing the number of minutes, followed by a capital letter M.
      3. The following component:
        1. At least one digit representing the number of seconds.
        2. Optionally a period or full stop character ("."), followed by the fractional part of the seconds composed by one, two or three digits.
        3. A capital letter S.

In favor of readability, spaces can be added inside any duration time component, except inbetween the digits composing the numbers.

Example

<time>P 25D</time>
<time>P 2D T 20H 5M 32.215S</time>
<time>PT 2H 5M</time>
<time>PT 22H 5.2S</time>

Examples

In the following example, a couple of sentences are providing dates informally, both accompanied by their machine-readable versions in the datetime attribute.

<p>We got married on <time datetime="1982-10-06">the 6th October, back in 1982</time>. <time datetime="1982-11-06">A month later</time> we knew Brian was coming.</p>

We got married on . we knew Brian was coming.

The second example shows a news fragment with the publication date in its footer. As before, the date is provided informally but with a very accurate version in the datetime attribute, possibly intended for script interaction.

<article>
  <h1>Turkey faces flood of refugees from Syria</h1>
  <p>The United Nations said Monday it is stepping up assistance to Turkey in the face of a worsening refugee crisis, as thousands of Kurds flee Islamic militants in Syria...</p>
  <footer>Published <time datetime="2014-09-15">a week ago</time>.</footer>
</article>

Turkey faces flood of refugees from Syria

The United Nations said Monday it is stepping up assistance to Turkey in the face of a worsening refugee crisis, as thousands of Kurds flee Islamic militants in Syria...

Published .

In this last example, the datetime attribute is absent, and the contents of the time element are the only version of the date it represents. It's clear how in this case, the contents of the element fit the requirements of a machine-readable time, and that the presence of the datetime attribute would be redundant.

<h1>Michael Parson</h1>
<p>Age: 26 years<br>
  Birthdate: <time>1982-05-15</time><br>
  Birthplace: Ontario, Canada
</p>

Michael Parson

Age: 26 years
Birthdate:
Birthplace: Ontario, Canada

Attributes

Specific attributes

datetime

A machine-readable representation of the element's contents.

The presence of this attribute in the time element isn't mandatory, but if it's absent, the element cannot have any descendants.

Example

<p>Eli is coming home <time datetime="2005-12-13">next week</time>.</p>

Eli is coming home .

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.