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
Absolute format
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 the day, month, and full year by default (for example: Jan 03, 2022). The date can be shortened to the day and month when space is tight (Jan 03). If the date is shortened, show the full date and time data in a tooltip, along with the timezone (Jan 03, 2022 11:00am UTC-8).
- Use the
numeric
value of theyear
parameter to display the year in full (for example: 2022). The2-digit
value may be used instead to display the shortened version of the year if there is limited space (22). - For the
month
parameter, use theshort
value (for example: Mar). Note that the API will auto-adjust tofull
if the language can't be shortened. - For the
day
parameter, use the2-digit
value. (For example: 01) - For
timeZoneName
, use eithershort
(for example: UTC-8) orlong
(for example: Pacific Standard Time), depending on space and what is needed to make the time zone clear in context.
- Use the
- ISO 8601 format is displayed YYYY-MM-DD. Time can also be appended to the end of the date if necessary (HH:MM:SS).
Relative format
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.
Guidelines
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, HH:MM:SS).
Exceptions
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: