RelativeTime

  • Alpha
  • Not reviewed for accessibility
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

Props

RelativeTime

NameTypeDefaultDescription
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
ref
React.RefObject<RelativeTimeElement>
A ref to the element rendered by this component. Because this component is polymorphic, the type will vary based on the value of the as prop.
as
React.ElementType
"relative-time"The underlying element to render — either a HTML element name or a React component.
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

Status

Alpha

  • Component props and basic example usage of the component 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 robust unit test coverage (100% where achievable).
  • Component has visual regression coverage of its default and interactive states.
  • Component does not introduce any axe violations.
  • Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

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 does not introduce any performance regressions.

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.
  • Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.