README

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="2021-10-06T16:11:39.563Z" datetime="2021-10-06T16:11:39.563Z">
  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}" />

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",
  }}"
/>

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

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

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

Name	Type	Default value
timestamp	`string` \| `number` \| `Date` \| `Dayjs`	`new Date().toISOString()`
format	`string`	`"MMM DD, YYYY"` (See dayjs display format)
relative	`boolean`	`false`
live	`boolean` \| `number`	`false`
formatted	`string`	`""`

Examples

The examples folder contains sample set-ups.

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

Usage no npm install needed!