Light SST Light Dark SST Dark System

Relative Time

<sl-relative-time> | SlRelativeTime
Since 2.0 stable

Outputs a localized time phrase relative to the current date and time.

Localization is handled by the browser’s Intl.RelativeTimeFormat API. No language packs are required. 

<!-- Shoelace 2 release date 🎉 -->
<sl-relative-time date="2020-07-15T09:17:00-04:00"></sl-relative-time>

import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';

const App = () => <SlRelativeTime date="2020-07-15T09:17:00-04:00" />;

The date attribute determines when the date/time is calculated from. It must be a string that Date.parse() can interpret or a Date object set via JavaScript.

Examples

Keeping Time in Sync

Use the sync attribute to update the displayed value automatically as time passes.

<div class="relative-time-sync">
  <sl-relative-time sync></sl-relative-time>
</div>

<script>
  const container = document.querySelector('.relative-time-sync');
  const relativeTime = container.querySelector('sl-relative-time');

  relativeTime.date = new Date(new Date().getTime() - 60000);
</script>

import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';

const date = new Date(new Date().getTime() - 60000);

const App = () => <SlRelativeTime date={date} sync />;

Formatting Styles

You can change how the time is displayed using the format attribute. Note that some locales may display the same values for narrow and short formats. 



<sl-relative-time date="2020-07-15T09:17:00-04:00" format="narrow"></sl-relative-time><br />
<sl-relative-time date="2020-07-15T09:17:00-04:00" format="short"></sl-relative-time><br />
<sl-relative-time date="2020-07-15T09:17:00-04:00" format="long"></sl-relative-time>

import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';

const App = () => (
  <>
    <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="narrow" />
    <br />
    <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="short" />
    <br />
    <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="long" />
  </>
);

Localization

Use the lang attribute to set the desired locale.

English:
Chinese:
German:
Greek:
Russian: 
English: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="en-US"></sl-relative-time><br />
Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="zh-CN"></sl-relative-time><br />
German: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="de"></sl-relative-time><br />
Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="el"></sl-relative-time><br />
Russian: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="ru"></sl-relative-time>

import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';

const App = () => (
  <>
    English: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="en-US" />
    <br />
    Chinese: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="zh-CN" />
    <br />
    German: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="de" />
    <br />
    Greek: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="el" />
    <br />
    Russian: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="ru" />
  </>
);

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.11.0/cdn/components/relative-time/relative-time.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.11.0/cdn/components/relative-time/relative-time.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/relative-time/relative-time.js';

To import this component as a React component:

import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';

Properties

Name Description Reflects Type Default
date The date from which to calculate time from. If not set, the current date and time will be used. When passing a string, it’s strongly recommended to use the ISO 8601 format to ensure timezones are handled correctly. To convert a date to this format in JavaScript, use date.toISOString(). Date | string new Date()
format The formatting style to use. 'long' | 'short' | 'narrow' 'long'
numeric When auto, values such as “yesterday” and “tomorrow” will be shown when possible. When always, values such as “1 day ago” and “in 1 day” will be shown. 'always' | 'auto' 'auto'
sync Keep the displayed value up to date as time passes. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.