svelte-time

Svelte component and action to format a timestamp using day.js

This utility wraps the date-time library day.js as a declarative Svelte component and action.

Use cases

• format a timestamp using the semantic time element
• display a human-readable, relative time (e.g., "4 days ago") while preserving the original timestamp

Sample output:

<time title="May 15, 2022" datetime="2022-05-15T18:03:57.430Z">
  a few seconds ago
</time>

Try it in the Svelte REPL.

Installation

# Yarn
yarn add -D svelte-time

# npm
npm i -D svelte-time

# pnpm
pnpm i -D svelte-time

Usage

Time component

The displayed time defaults to new Date().toISOString() and is formatted as "MMM DD, YYYY".

<script>
  import Time from "svelte-time";
</script>

<Time />

The timestamp prop can be any of the following dayjs values: string | number | Date | Dayjs.

<Time timestamp="2020-02-01" />

<Time timestamp={new Date()} />

<Time timestamp={1e10} />

Use the format prop to format the timestamp. Refer to the dayjs format documentation for acceptable formats.

<Time timestamp="2020-02-01" format="dddd @ h:mm A · MMMM D, YYYY" />

<Time timestamp={new Date()} format="YYYY/MM/DD" />

<Time timestamp={1e10} format="ddd" />

Relative time

Set the relative prop value to true for the relative time displayed in a human-readable format.

<Time relative />

<Time relative timestamp="2021-02-02" />

<Time relative timestamp={1e10} />

When using relative time, the title attribute will display a formatted timestamp.

Use the format prop to customize the format.

<Time relative format="dddd @ h:mm A · MMMM D, YYYY" />

Live updates

Set live to true for a live updating relative timestamp. The default refresh interval is 60 seconds.

<Time live relative />

To customize the interval, pass a value to live in milliseconds (ms).

<!-- Update every 30 seconds -->
<Time live={30 * 1000} relative />

<!-- Update every 10 minutes -->
<Time live={10 * 60 * 1000} relative />

svelteTime action

Use the svelteTime action to format a timestamp in a raw HTML element.

<script>
  import { svelteTime } from "svelte-time";
</script>

<time use:svelteTime />

<time
  use:svelteTime={{
    timestamp: "2021-02-02",
    format: "dddd @ h:mm A · MMMM D, YYYY",
  }}
/>

<time
  use:svelteTime={{
    relative: true,
    timestamp: "2021-02-02",
  }}
/>

<time
  use:svelteTime={{
    relative: true,
    timestamp: "2021-02-02",
    format: "dddd @ h:mm A · MMMM D, YYYY",
  }}
/>

Similar to the Time component, the live prop only works with relative time.

<time
  use:svelteTime={{
    relative: true,
    live: true,
  }}
/>

Specify a custom update interval using the live prop.

<time
  use:svelteTime={{
    relative: true,
    live: 30 * 1_000, // update every 30 seconds
  }}
/>

Custom locale

Load a custom locale and set it as the default locale using the dayjs.locale API.

<script context="module">
  import "dayjs/esm/locale/de";
  import dayjs from "dayjs/esm";

  dayjs.locale("de"); // German locale
</script>

<script>
  import Time from "svelte-time";
</script>

<Time />

dayjs export

dayjs is re-exported for your convenience. This is useful when the component and action would not work for programmatic usage, like setting the document title.

Note: the exported dayjs function already extends the relativeTime plugin.

<script>
  import { dayjs } from "svelte-time";
</script>

<button on:click={() => (document.title = dayjs().format("MMM DD, YYYY"))}> Set title </button>

API

Props

Examples

The examples folder contains sample set-ups.

• examples/sveltekit
• examples/vite
• examples/sapper
• examples/snowpack
• examples/rollup
• examples/webpack

TypeScript

Svelte version 3.31 or greater is required to use this component with TypeScript.

TypeScript definitions are located in the types folder.

Changelog

CHANGELOG.md

License

MIT