RelativeTime

Alpha
Not reviewed for accessibility

Source

On this page

import {RelativeTime} from '@primer/react'

Formats a timestamp as a localized string or as relative text that auto-updates in the user's browser.

Examples

Default

<>
  <RelativeTime datetime="2014-04-01T16:30:00-08:00" />
  <br/>
  <RelativeTime date={new Date('2014-04-01T16:30:00-08:00')} format="micro" tense="past"/>
  <br/>
  <RelativeTime datetime="2014-04-01T16:30:00-08:00" format="elapsed"/>
</>

<>
  <RelativeTime datetime="2014-04-01T16:30:00-08:00" />
  <br/>
  <RelativeTime date={new Date('2014-04-01T16:30:00-08:00')} format="micro" tense="past"/>
  <br/>
  <RelativeTime datetime="2014-04-01T16:30:00-08:00" format="elapsed"/>
</>

Props

RelativeTime

Name	Type	Default	Description
datetime Required	string		An ISO8601 time represeting the time
date	string		Instead of passing the `datetime`, it is possible to pass a full `Date` object into the `date` prop
format	'auto' \| 'micro' \| 'elapsed'	'auto'	The format with which to display the time
tense	'auto' \| 'past' \| 'future'	'auto'	The tense to use when displaying a relative time
precision	'year' \| 'month' \| 'day' \| 'hour' \| 'minute' \| 'second'	'second'	The precision to use when displaying an elapsed time
threshold	string	'P30D'	The threshold (ISO8601 duration) to display relative dates within
prefix	string	'on'	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' \| '2-digit' \| 'short' \| 'long' \| 'narrow'	'numeric'	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
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.
ref	React.RefObject<RelativeTimeElement>		A ref to the element rendered by this component.
Additional props are passed to the `<relative-time>` element. See @github/relative-time-element for a list of props accepted by the `<relative-time>` element.

Status

Alpha

Component props are documented on primer.style/react.
Component does not have any unnecessary third-party dependencies.
Component can adapt to different themes.
Component can adapt to different screen sizes.
Component has 100% test coverage.

Beta

Component is used in a production application.
Common usage examples are documented on primer.style/react.
Common usage examples are documented in storybook stories.
Component has been reviewed by a systems designer and any resulting issues have been addressed.
Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Stable

Component API has been stable with no breaking changes for at least one month.
Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
Component has corresponding design guidelines documented in the interface guidelines.
Component has corresponding Figma component in the Primer Web library.

Edit this page on GitHub

1 contributor

Last edited by keithamus on December 6, 2022