Date and time
Dates and times clarify when an event occurred. The way they are formatted should be informative, not disruptive. While users can choose a preferred date and time format, there are occasions when we default to a specified format instead.
Date and time options
The absolute format clarifies the precise date and time that something occurred.
Absolute date and time information can be localized to display a user's local date and time or follow the ISO 8601 format. See the Guidelines section for more information about when dates should be localized, and when they should be shown in ISO 8601.
- Localized dates display as
Jan 03, 2021or are shortened to
Jan 03when space is tight. Always show the full date and time data, along with the timezone, in a tooltip if the date is shortened. Both
timeStyleshould be set to medium.
- ISO 8601 format is displayed
YYYY-MM-DD. Time can also be appended to the end of the date if necessary as
The relative format communicates the approximate amount of time that has passed since an event occurred; whether that event occurred XX minute(s), hour(s), day(s), week(s), month(s), or year(s) ago. For example, it is used to communicate that an issue was opened
1 minute ago or
10 months ago.
When using the relative format, always display the absolute time in a tooltip following the Guidelines below.
Which format to use when
- Display date and time information in the absolute format unless users specify they want to use relative formatting instead.
- If it's possible to detect the browser settings, display the localized time, for example
Jan 03, 2021. Otherwise, fall back to displaying the date in ISO 8601:
YYYY-MM-DD(time is optionally appended after the date,
In certain scenarios, the date and time are displayed in a specific format and the user's preference is overridden.
Use absolute format when:
- Users need specific dates and/or times for technical, security, or legal reasons. For example, in an audit log, a tax form, or a security alert.
- Users would need to convert relative time to absolute time in order to complete a task.
- A range of time is displayed, for example in a date picker.
Use relative format when:
- Content is updated frequently and specifics are not critical. For example, a live newsfeed or notification.
Adding timezone data
In situations where timezone context is important, for example in alerts or incidents, append the timezone information to the end of the date and time.
Last updated at: