RelativeTime

RelativeTime displays time in a way that is clear, concise, and accessible.

Page navigation navigation

React

ready

Storybook|Source

Rails

ready

Docs|Lookbook|Source

This component's features all come from the relative-time-element (GitHub staff only) custom element.

React examples

Default

Jan 2, 2020

<RelativeTime date={new Date('2020-01-02T00:00:00Z')} />

<RelativeTime date={new Date('2020-01-02T00:00:00Z')} />

With time

Jan 2, 2020

<RelativeTime second="numeric" minute="numeric" hour="numeric" date={new Date('2020-01-02T01:02:03Z')} />

<RelativeTime second="numeric" minute="numeric" hour="numeric" date={new Date('2020-01-02T01:02:03Z')} />

With leading zeros

Number formatting guidelines

Jan 2, 2020

<RelativeTime day="2-digit" second="2-digit" minute="2-digit" hour="2-digit" date={new Date('2020-01-02T01:02:03Z')} />

<RelativeTime day="2-digit" second="2-digit" minute="2-digit" hour="2-digit" date={new Date('2020-01-02T01:02:03Z')} />

Without "on" prefix

Word formatting guidelines

Jan 2, 2020

<RelativeTime date={new Date('2020-01-02T01:02:03Z')} prefix="" />

<RelativeTime date={new Date('2020-01-02T01:02:03Z')} prefix="" />

Micro format

Jan 2, 2020

<RelativeTime format="micro" date={new Date('2020-01-02T01:02:03Z')} />

<RelativeTime format="micro" date={new Date('2020-01-02T01:02:03Z')} />

Without a title attribute

Jan 2, 2020

<RelativeTime date={new Date('2020-01-02T01:02:03Z')} noTitle={true} />

<RelativeTime date={new Date('2020-01-02T01:02:03Z')} noTitle={true} />

Jan 2, 2020

<Tooltip text={new Date('2020-01-02T01:02:03Z').toString()}>
  <Link href="#">
    <RelativeTime date={new Date('2020-01-02T01:02:03Z')} noTitle={true} />
  </Link>
</Tooltip>

<Tooltip text={new Date('2020-01-02T01:02:03Z').toString()}>
  <Link href="#">
    <RelativeTime date={new Date('2020-01-02T01:02:03Z')} noTitle={true} />
  </Link>
</Tooltip>

Props

RelativeTime

Name	Default	Description
datetime Required		`string` An ISO8601 time representing the time
date		`string` Instead of passing the `datetime`, it is possible to pass a full `Date` object into the `date` prop
format	`'auto'`	`'auto' \| 'micro' \| 'elapsed'` The format with which to display the time
tense	`'auto'`	`'auto' \| 'past' \| 'future'` The tense to use when displaying a relative time
precision	`'second'`	`'year' \| 'month' \| 'day' \| 'hour' \| 'minute' \| 'second'` The precision to use when displaying an elapsed time
threshold	`'P30D'`	`string` The threshold (ISO8601 duration) to display relative dates within
prefix	`'on'`	`string` The prefix to use when displaying a localised (non relative) date
second		`'numeric' \| '2-digit'` The format with which to render seconds
minute		`'numeric' \| '2-digit'` The format with which to render minutes
hour		`'numeric' \| '2-digit'` The format with which to render hours
weekday		`'short' \| 'long' \| 'narrow'` The format with which to render weekdays
day		`'numeric' \| '2-digit'` The format with which to render days
month	`'numeric'`	`'numeric' \| '2-digit' \| 'short' \| 'long' \| 'narrow'` The format with which to render months
year		`'numeric' \| '2-digit'` The format with which to render years
timeZoneName		`'long' \| 'short' \| 'shortOffset' \| 'longOffset' \| 'shortGeneric' \| 'longGeneric'` The format with which to render the time zone
ref		`React.RefObject<RelativeTimeElement>`
noTitle		`boolean` Removes the `title` attribute provided on the element by default
attributeChangedCallback		`(attrName: string, oldValue: unknown, newValue: unknown) => void`
connectedCallback		`() => void`
onRelativeTimeUpdated		`null \| (event: RelativeTimeUpdatedEvent) => void`
update		`() => void`
as	`"relative-time"`	`React.ElementType`
sx Deprecated		`SystemStyleObject`