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.

We can either display a localized time and date format based on the user's location or use a non-localized format following the ISO 8601 standard.

  • Localized dates display the day, month, and full year by default (for example: Jan 3, 2022). The date can be shortened to the day and month when space is tight (Jan 3). If the date is shortened, show the full date and time data in a tooltip, along with the timezone (Jan 3, 2022 11:00am UTC-8).
    • Use the numeric value of the year parameter to display the year in full (for example: 2022). The shortened version of the year may be used instead if there is limited space (22).
    • For the month parameter, use the short value (for example: Mar). Note that the API will auto-adjust to full if the language can't be shortened.
    • For the day parameter, use the numeric value. (For example: 1)
    • For timeZoneName, use either short (for example: UTC-8) or long (for example: Pacific Standard Time), depending on space and what is needed to make the time zone clear in context.
  • 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 3, 2021. Otherwise, fall back to displaying the date in ISO 8601: YYYY-MM-DD (time is optionally appended after the date, HH:MM:SS).
graph TD A["Which date/time
format to use?"]:::start B{"Does the
situation meet exceptions
for always use absolute
format?"}:::decision C{"Does the
situation meet exceptions
for always use relative
format?"}:::decision D{"Does user set
'Use relative format'
in preferences?
(on by default)"}:::decision E{"Can browser detect
user's region
automatically?"}:::decision F{"Is there limited
space to display?"}:::decision G["Use Absolute:
localized normal format, Ex: Jan 2, 2021
(European style)"]:::ending H["Use Absolute:
localized format (shortened), Ex: Jan 2
(European style)"]:::ending I["Use Absolute:
ISO 8601 format, Ex: YYYY-MM-DD"]:::ending J["Use Relative format
Ex: 30 minutes ago"]:::ending A --> B B -->|Yes| E B -->|No| C C -->|Yes| J C -->|No| D D -->|Yes| J D -->|No| E E -->|Yes| F E -->|No| I F -->|Yes| H F -->|No| G classDef start fill:#DCFBFC, stroke:#20757D classDef decision fill:#FEF3D7, stroke:#DAA520 classDef ending fill:#D7BED7, stroke:#63397

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: