Grow your CSS skills. Land your dream job.

The `time` Element

Published by Chris Coyier

The following is a guest post by Ty Strong. Ty noticed a curious lack of information on the <time> element here on CSS-Tricks and I agreed. Can't let that happen! Take it away Ty.

The <time> element in HTML represents a machine-readable date, time, or duration. It can be useful for creating event scheduling, archiving, and other time-based functions. WordPress uses the time element in the default theme. Reddit uses the time element as well.


Reddit using the <time> element for posting dates.

A Brief History

The time element has had a rocky road. It was added to the HTML5 specs back in 2009. Two years later in 2011, the spec was dropped and replaced with a much broader element, <data>. Later that year the time element was added back with some revamped features.

Rest assured, you can use it!

Bruce Lawson covers the situation well: gone, back, now. A classic "paving the cowpaths" moment in HTML history.

The Tag and Attribute

Time is just an HTML tag. Here's a simple example that represents November 2011:

<time>2011-11</time>

The text in there happens to be a valid datetime attribute value (more on that in a moment). But it doesn't have to be. You could move that text into a datetime attribute and use different text.

<time datetime="2011-11">A cold winter month many years ago</time>

The datetime attribute is what makes the time element unique. It represents the date, time, or duration for whatever text you are representing in a machine readable format. That means it is for computers, not humans, so it has very specific formats.

It's probably a bit more common for the human-readable version to be just a textual representation of the datetime:

<time datetime="2011-11">November, 2011</time>

10 Ways

There are a variety of standard ways to format the datetime attribute.

Year and Month

2014-06

Very Simple. Year before month.

Date

1969-07-16

Year, month, and then day.

Yearless Date

12-31

Month before day.

Time Only

14:54:39.929

Hour, minute, then seconds. Seconds is optional. Fractions of a second can be represented up to three digits.

Date and Time

2013-11-20T14:54

Combination of Date and Time, separated by a capital T. The capital "T" can be replaced with a space.

Time-Zone Offset

+06:00

Starts with plus or minus sign. Colon (:) is optional. +00:00, or UTC time, can be represented by the capital letter "Z".

Local Date and Time

2019-12-31T23:59:59-02:00

This is the same as Date and Time with an added time-zone offset. Again, "T" can be replaced with a space.

Year and Week

2010-W21

Year followed by a capital "W" with the corresponding number week.

Year Only

1776

This must be four digits or more, so `0001` and `12345` both work.

Duration (Method One)

P2DT2H30M10.501S

Capital "P", an optional day value, capital "T", then optional values of hours, minutes, and seconds. All letters must be upper-case.

Duration (Method Two)

1w 2d 2h 30m 10.501s

Week (w), Day (d), Hour (h), Minute (m), and Seconds (s). Letter can be upper-case or lower-case. Spaces are optional.

Examples

Google released Gmail Blue on <time datetime="2013-04-01">April 1st, 2013</time>.
The Chelyabinsk meteor entered Earth's atmosphere over Russia on <time datetime="2013-02-15T09:20+06:00">15 February 2013 at about 09:20 YEKT (03:20 UTC)</time>.
The Apollo 13 mission lasted a total of <time datetime="5d 22h 54m 41s">5 days, 22 hours, 54 minutes, and 41 seconds</time>.

Having Trouble Formatting the Datetime?

Using this little tool you can input a certain date or time (or both), and it will output the correct datetime value.

See the Pen Datetime Creator Tool by Chris Coyier (@chriscoyier) on CodePen.

Browser Support

Browser support isn't a major concern with the time element. If a browser is familiar with it, great, if not, it will treat it as a generic inline element which is perfectly fine. The datetime attribute is also perfectly accessible.

There is a DOM interface associated with the time element though. Specifically dateTime should be available on a reference to that element.

<p>The concert took place on <time datetime="2001-05-15 19:00">May 15</time>.</p>
<script>
  var time = document.getElementsByTagName("time")[0];
  console.log(time.dateTime);
  // outputs "2001-05-15 19:00"
</script>

This is only supported in Firefox, and isn't particularly useful anyway since all it does is return that attribute (it doesn't even return a value value if the attribute isn't there but the text is a valid value, which seems like it would make sense.)

What is the benefit to using <time>?

I'm going to quote Bruce again because he says it very well in a post on HTML5 Doctor:

The uses of unambiguous dates in web pages aren’t hard to imagine. A browser could offer to add events to a user’s calendar. A Thai-localised browser could offer to transform Gregorian dates into Thai Buddhist era dates. A Japanese browser could localise <time>16:00</time> to "16:00時". Content aggregators can produce visual timelines of events.

Search engines can produce smarter search results. For example, in the recent heavy snow in the UK, I searched for school closures in my town and discovered my kids’ school was closed. After receiving a phone call from the school asking me where my kids were, I re-examined the webpage. In small print at the bottom of the page were the words "Published 5 January 2008". I expect that operators of search engines would rank more current pages more highly on searches connected with current events.

Other Bits

A further touch you can do to the time element is adding a title attribute to expose more detailed information to the user. Meaning you can offer the same bit of information three ways:

  • A nice human-readable display format
  • A more detailed human-readable hover format
  • A machine-readable format

This is in use on CodePen:

This is the Rails code that outputs those different formats (STRFTIME is a nice tool for that):

<time 
  datetime="<%= @pen.created_at.strftime("%Y-%m-%dT%H:%M") %>"
  title="<%= @pen.created_at.strftime("%Y-%m-%d at %I:%M %p") %>">
    <%= @pen.created_at.strftime("%B %d, %Y") %>
</time>

Are you using <time> on any of your projects?

Comments

  1. Bruno Giubilei
    Permalink to comment#

    its a nice native component, but its avaible for Chrome only, in firefox is not suported.

    Font: http://html5test.com/

    • Not sure where you’re seeing this but according to caniuse it’s compatible with every major browser (if you’re not counting ie8). Interestingly enough, MDN seems to think that it is not supported in Chrome.

    • Whether the browser technically supports the element or not, the time element will still function correctly with most javascript functions. It will also display correctly, since it will still display as an inline-block by default.

    • I’ve updated MDN article according to caniuse, just waiting for review.

  2. Miguel Ripoll
    Permalink to comment#

    Would I use it with relative times? If so, a complete date should be on the attribute I guess.

    • Yes, you can use it with most relative times. For the time of day, you can simply leave out the time-zone offset. For dates, you can choose broader spans such as a certain week, a month, or year. The exceptions are specifying something such as “Sometime in the 18th century”.

  3. Thanks for clearing it up, Ty. The time element is hard to track down information on because it’s changed status so much.

    One thing that’s bothering me about using it is that this markup won’t validate:

    Aug 31st, 2013
    

    I get the following error on w3.org validator, which is likely wrong:

    Bad value 2013-09-31 for attribute datetime on element time: Day out of range.

    I’m not sure what ‘range’ it’s looking for, but a quick Google searches turned up nothing.

    • nkrisc
      Permalink to comment#

      Aug 31st, 2013 is not the same as 2013-09-31.

      2013-09-31 is September 31st, 2013, which doesn’t exist.

      YEAR-MONTH-DATE is the correct format.

    • There isn’t a 2013-09-31, only a 2013-09-30.

    • Ha! Mathis is totally correct. There is no August 31, 2013! So much for putting random dates on pages.

      Thanks, Mathias!

    • MaxArt
      Permalink to comment#

      There is an August 31st. There’s no September 31st, though.

  4. I’ve used “ on projects before where I’ve implemented Microformats. In the past, to use the h-event format (previously hCalendar), you would mark up start and end dates/times using a semantically-queezy <abbr> element:

    <abbr title="2014-06-30">June 30, 2014</abbr>
    

    But now, we can just use “ as illustrated here:

    June 30, 2014
    

    It feels more correct.

    • Hmmm, comment parser doesn’t like time to be in the brackets. Sorry. That first sentence should read “I’ve used time on projects…”, and the statement before the second example should read “But now, we can just use time as illustrated here:”

  5. Nice explanation! We used the time element on our redesign of TechCrunch.

  6. MaxArt
    Permalink to comment#

    Very informative. It’s not easy to collect all these info together with the goal of this (rather uncommon) element.

    I’ve used it sometimes, but I mainly develop web applications that aren’t indexed by search engines, so its role is weak. For me the worst part is that IE8 and lower can’t stylize it without the old html5-shiv trick. So watch out.

  7. As we advance our markups in building webpages, the more complicated it becomes and the more specific it is. Then after this there goes schema.org’s micro-formatting…

  8. Nice explanation! I’ve been using time for all post date in WordPress websites and I use PHP to output datetime attribute like this the_time( 'c' ).

  9. Chris D.
    Permalink to comment#

    After reading this post, I still cannot see the difference between:
    April 1st, 2013
    and
    April 1st, 2013

    There is this…

    The datetime attribute is what makes the time element unique. It represents the date, time, or duration for whatever text you are representing in a machine readable format. That means it is for computers, not humans, so it has very specific formats.

    However that is easy to do, for example:
    April 1st, 2013

    So, question is, why another tag and not just a class?

    • Chris D.
      Permalink to comment#

      How do I edit comment? :-/

      Chris C. Note: [Inline Code] code button did not work in output. Does not display the code, instead it was parsed as html :-/

      Difference?
      <time datetime=”2013-04-01″>April 1st, 2013</time>

      <span data-datetime=”2013-04-01″ class=”time”>April 1st, 2013</span>

    • Technically, you could use <div> tags for paragraphs, bold text, list items, and buttons. Although you can do it, there are better, more specific tags that you could use. Part of the reason for bringing back the time tag and not using the generic data tag was to have a more specific tag just for dates, time, and durations. I hope that helped!

  10. Thanks for this post, Ty!
    I have to admit, I’m not really aware of the use of the “ element, so thank you to have written this post ! I hope it will make people understand better the use of this element, as it does for me !

  11. leopinzon

    Excelent post Ty. Do you have any other advise for using it correctly for Seo practices? Is there something more to have in mind or this is the all recipe?
    Congrats again!

    • Thank you! Search Engines have started (or will start soon) using the time tag to help find more recent published articles, ranking them higher. This can help you when you first publish the article, but might start to hurt you later on if your article is very old. An idea to keep your article ranked higher could be to add something like this to your page: “Article last updated on _ time tag_”

  12. I love the idea of using the <time> to improve search results for time sensitive queries (e.g. weather updates, sport updates, disaster updates, etc.), but I can see this going south real fast. What’s to stop someone from putting a small script on their page that outputs the current date and time every time the page is loaded?

    For accessibility and semantics? This element is wonderful.
    For SEO? Hopefully someday, but right now it’s sadly just not ready for the prime time.

  13. Great article Ty.
    I have a question, how would you do if you want to display something like: 2 days ago ?
    Thanks

    • Use a time-Element only, if you have a concrete date, time or duration. Otherwise don’t use a time-Element.

    • @Mathias, although at the same time the <time> element can add a concrete date, time or duration to something as vague as 2 days ago.

      @Patricio, you could mark it up like this…

      <time datetime='2014-06-30'>2 days ago</time>
    • <time datetime=’2014-06-30′>2 days ago</time>

      Yes, its true. But it is only possible if you know this particular date.

      Example: If you want to participate in the tests, you must log in first 2 days in advance.

    • @James thank you for you comment on that.
      @Mathias that’s a very good point.
      Thank you very much.

  14. What about the pubdate attribute?

    <time datetime="" pubdate></time>
    • The attribute pubdate has been dismissed from both the WHATWG and W3C specs. Back in 2011 when the time element made it’s reappearance, pubdate did not come back with it.

  15. I always use time on blog publishing dates. My current blog uses Jekyll, which makes it pretty easy:

    <time class=”meta” datetime=”{{ page.date }}”>{{ page.date | date_to_string }}</time>

    (you can look at the source code if you like, it’s open source. I took that snippet from this file )

  16. Chris D.

    Thanks Ty for clearing that up.
    I assumed that was the case.

  17. Tiji

    <time> tag indeed is an important tag which a lot of us can easily overlook. Thanks for the article. I’m sure a lot of us would remember to use the time tag henceforth.

  18. Permalink to comment#

    Great article Ty.
    I have a question, how would you do if you want to display something like: 2 days ago ?
    Thanks

This comment thread is closed. If you have important information to share, you can always contact me.

*May or may not contain any actual "CSS" or "Tricks".