Criteria

RelativeAbsoluteISO
When to useUsers need to quickly see how long ago an event occurred, or how far in the future it will occur, and they don't need the specific datetime.Users need a specific date and time for when an event occurred or will occur.Users need a specific date and time in the standardized ISO format (typically when using timestamps in code).

Examples

Relative

Creation date
5 hours ago by plrs


Scan completed
6 days ago

Absolute

Creation date
January 31, 2010, 14:32 (UTC+3:30) by plrs


Bucket deleted
January 31, 2010, 14:56 (UTC+3:30) by plrs

ISO

{ "creationDate": "2010-01-19T14:32:35+03:00" }

Key UX Concepts

Formats

Use the timestamp that’s most appropriate to your users' needs. Relative timestamps are easier for users to read, so we recommend them for most use cases.

Labels

Timestamps should always be accompanied by a label that clearly and consistently describes what event the timestamp references. You can display a timestamp label with the timestamp, above it as a heading (such as the key in a key-value pair), or as a column header in a table.

For example: Resource edited

Source of change

When it’s important to identify who or what made a change, add the user or system's name after the timestamp and link to its profile.

For example: Template edited 6 hours ago by plrs

Formats

Relative timestamps

Relative timestamps for events in the past use the format: [number] [unit of time] ago

For example: 36 minutes ago

Use the plural form of the time unit when necessary.

For example: 1 year or 2 years

When the event is happening in the future, use the format: In [number] [unit of time]

For example: In 36 minutes

Relative timestamp units

Use the level of granularity appropriate for the event.

Time FrameUnit
0 – 59 secondsNow
1 – 59 minutes# minutes ago
1 – 24 hours# hours ago
1 – 31 days# days ago
1 – 4 weeks# weeks ago
1 – 12 months# months ago
More than 12 months # years ago

Absolute timestamps

Absolute timestamps in the US, Canada, Palau, Micronesia, and the Philippines use this format: "Month DD, YYYY, hh:mm (UTC±h:mm)".

For example: January 31, 2010, 14:32 (UTC+3:30)

For additional timestamp locale formats, you can use localization libraries.

ISO timestamps

ISO timestamps use the ISO 8601  format: YYYY-MM-DDThh:mm:ss±hh:mmZ

For example: 2010-01-31T14:32:35+03:00

In the ISO timestamp, T is used as a divider between the date and time and Z is the zone designator for the zero UTC offset. If the timestamp is doesn't require time granularity, only display the date portion of the timestamp.

For example: 2010-01-31

General guidelines

Do

  • Since relative dates are easier to read, we recommend using them in most situations.
  • When reporting usage for billing, relative timestamps should use the same time unit as the resource is being billed at. For example, for a resource billed by the hour, use 32 hours, not "1 day, 8 hours".

Don't

  • Don't abbreviate the words in timestamps. For example, always use January, not "Jan", and seconds not "sec".

Writing guidelines

Labels

  • Use the following format: [Noun] [verb] where [Noun] is the resource, item, or task, and [verb] is the event that occurred or will occur.

    • For example: Endpoint created, Template edited, or Scan terminates.

  • For events that occurred in the past, use past tense.

    • For example: Certificate expired

  • For events that occur in the future, use future tense.

    • For example: Certificate expiring

  • Don't include "date", "time", or "timestamp" in the label (with one exception, below).

    • For example: Use Role modified instead of Role modified date

  • In tables, where you report the status of a number of resources, processes, or activities that won't all begin or end at the same time, use the format: [noun] [verb] time

    • For example: Training job start time or Training job end time

    • Add "last" to a label only when the event can reoccur and users need to know the most recent occurrence.

      • For example: Role last modified

Source of change

Use the format: [label] [timestamp] by [name]. The name is the user or service that made the change.

  • For example: Template edited 6 hours ago by plrs

Accessibility guidelines

General accessibility guidelines

  • Follow the guidelines on alternative text and Accessible Rich Internet Applications (ARIA) regions for each component.

  • Make sure to define ARIA labels aligned with the language context of your application.

  • Don't add unnecessary markup for roles and landmarks. Follow the guidelines for each component.

  • Provide keyboard functionality to all available content in a logical and predictable order. The flow of information should make sense.

  • Make sure you define ARIA labels for the selection inputs that are aligned with the language context of your application.

Relative timestamps

For relative timestamps, provide users access to the corresponding absolute timestamps by doing the following:

  1. Wrap the relative timestamp in a <time> element and set the datetime attribute to the absolute timestamp. For more information, see MDN documentation .

2. Set the <time> element's title attribute to the absolute timestamp, which allows users to hover over the timestamp to access the absolute format.

For example:  <time title="January 31, 2010, 14:32 (UTC+1:00)" datetime="January 31, 2010, 14:32 (UTC+1:00)">10 days ago</time>