Relative time
- Experimental
- Not reviewed for accessibility
Content
Past dates
For past dates, the relative time outputs different formats depending on the time difference.
Within a month's time, the output shows a relative time1 in the format of X seconds/minutes/hours/days ago. If the time difference is less than 1 minute, it shows just now.
If the date is in past months, the date time2 format on D MMM is used. If the date is in the past years, the format on D MMM, YYYY is used.
| Time difference | Format | Examples |
|---|---|---|
| < 1 minute | just now | just now |
| < 1 month | X seconds/minutes/hours/days ago | a minute ago, 5 minutes ago, an hour ago, 3 hours ago, yesterday, 20 days ago |
| > 1 month | on D MMM | on 18 Nov |
| Past year | on D MMM, YYYY | on 26 Aug, 2021 |
Future dates
Future dates also use different formats depending on the time difference.
If the future date is due to happen within the a month's time, the relative time outputs the format of in X seconds/minutes/hours/days. If the time difference is less than 1 minute, it shows just now.
If the date is in the following months, the format on D MMM is used. If the date is in the next year or further, the format on D MMM, YYYY is used.
| Time difference | Format | Examples |
|---|---|---|
| < 1 minute | just now | just now |
| < 1 month | in X seconds / minutes / hours / days | in a minute, in 2 minutes, in an hour, in 7 hours, tomorrow, in 14 days |
| > 1 month | on D MMM | on 18 Nov |
| Next year | on D MMM, YYYY | on 26 Aug, 2021 |
Micro format
The micro format shows a short version of the relative time. It's useful to display the relative time in a more compact space or in a mobile environment. For both past and future dates, the output shows the relative time in the format of Xs/h/d. If the date is in the following or past months, the format D MMM is used. If the date is in the following or past years, the format D MMM, YYYY is used.
| Time difference | Format | Examples |
|---|---|---|
| < 1 month | Xs/h/d | 1s, 20s, 5m, 40m, 1d, 20d |
| > 1 month | D MMM | 18 Nov |
| Past or next year | D MMM, YYYY | 26 Aug, 2021 |
Use the micro format to display time in a more compact space or in a mobile environment.
Don't use the micro format when there's a prominent space. Use the default option instead.
Usage
A relative time can be used within a sentence, following the action that it's relative to.
Standalone
A relative time can be used as an independent element when the content and the surrounding elements make it clear what the time is related to.
Use it in a list item where each item title references the action that was performed.
Use it in a timeline item where the section title references the action.
Responsive design
When used as standalone element, the default format can change to micro to fit in a narrow area.
Links
A relative time is used as plain text in most cases. However, it can be used as an anchor link to point to an element within a view that contains relevant or nested information. For example, as a link to a comment in a conversation.
Accessibility
A relative time is treated like a time element when it shows a local numerical date, and it contains an abbreviation element when it shows a relative date phrase.
- Relative time data is derived from the Intl.RelativeTimeFormat API.↩
- Date time data is derived from the Intl.DateTimeFormat API.↩
