Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

svelte-time

metonym20.2kMIT2.0.1TypeScript support: included

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

svelte, dayjs, time formatter, timestamp, relative, ago

readme

svelte-time

NPM

Note: `svelte-time@2.0.0` only supports Svelte 5 in Runes mode.

Use svelte-time@1.0.0 for Svelte 3, 4, and 5 (non-Runes mode).


svelte-time is a Svelte component and action to make a timestamp human-readable while encoding the machine-parseable value in the semantic time element.

Under the hood, it uses day.js, a lightweight date-time library.

<!-- Input -->
<Time relative />

<!-- Output rendered in the DOM -->
<time title="May 15, 2022" datetime="2022-05-15T18:03:57.430Z">
  a few seconds ago
</time>

Try it in the Svelte REPL.


Installation

# npm
npm i svelte-time

# pnpm
pnpm i svelte-time

# Bun
bun i svelte-time

# Yarn
yarn add 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" />

When using relative, the time element will set the formatted timestamp as the title attribute. Specify a custom title to override this.

<Time relative title="Custom title" />

Set the value to undefined to omit the title altogether.

<Time relative title={undefined} />

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 * 1_000} relative />

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

svelteTime action

An alternative to the Time component is to use the svelteTime action to format a timestamp in a raw HTML element.

The API is the same as the Time component.

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

<time use:svelteTime></time>

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

Relative time

Set relative to true to use relative time.

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

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

To customize or omit the title attribute, use the title prop.

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

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

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

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

Specify a custom update interval using the live prop.

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

dayjs export

The dayjs library is exported from this package for your convenience.

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

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

  let timestamp = $state("");
</script>

<button
  type="button"
  onclick={() => (timestamp = dayjs().format("HH:mm:ss.SSSSSS"))}
>
  Update {timestamp}
</button>

Custom locale

The default dayjs locale is English. No other locale is loaded by default for performance reasons.

To use a custome locale, import the relevant language from dayjs. See a list of supported locales.

<script>
  import "dayjs/locale/de"; // German locale
  import Time, { dayjs } from "svelte-time";
</script>

<Time timestamp={dayjs().locale("de")} format="dddd, MMMM D, YYYY" />

Custom locale (global)

Use the dayjs.locale method to set a custom locale as the default.

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

  // Set the default locale to German.
  dayjs.locale("de");
</script>

Custom timezone

To use a custom timezone, import the utc and timezone plugins from dayjs.

<script>
  import utc from "dayjs/plugin/utc";
  import timezone from "dayjs/plugin/timezone";

  import Time, { dayjs } from "svelte-time";

  dayjs.extend(utc);
  dayjs.extend(timezone);
</script>

<Time
  timestamp={dayjs("2013-11-18 11:55:20").tz("America/Toronto")}
  format="YYYY-MM-DDTHH:mm:ss"
/>

Custom timezone (global)

Use the dayjs.tz.setDefault method to set a custom timezone as the default.

<script>
  import utc from "dayjs/plugin/utc";
  import timezone from "dayjs/plugin/timezone";

  import Time, { dayjs } from "svelte-time";

  dayjs.extend(utc);
  dayjs.extend(timezone);
  dayjs.tz.setDefault("America/New_York");
</script>

User timezone

Use the dayjs.ts.guess method to guess the user's timezone.

import utc from "dayjs/plugin/utc";
import timezone from "dayjs/plugin/timezone";

dayjs.extend(utc);
dayjs.extend(timezone);

dayjs.tz.guess(); // America/New_York

To retrieve the abbreviated time zone, extend the advancedFormat plugin.

  import utc from "dayjs/plugin/utc";
  import timezone from "dayjs/plugin/timezone";
+ import advancedFormat from "dayjs/plugin/advancedFormat";

  import { dayjs } from "svelte-time";

  dayjs.extend(utc);
  dayjs.extend(timezone);
+ dayjs.extend(advancedFormat);

Then, use the dayjs().local method to get the user's local time zone and format it using the "z" advanced option.

dayjs().local().format("z"); // EST
dayjs().local().format("zzz"); // Eastern Standard Time

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

Changelog

CHANGELOG.md

License

MIT

changelog

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

2.0.1 - 2025-02-24

Fixes

  • fix svelteTime import in TypeScript definitions

2.0.0 - 2025-01-23

The library is modernized to only support Svelte 5 (Runes mode). There are no component API changes.

Use svelte-time@1.0.0 for Svelte 3/4 support. v1 is also compatible with Svelte 5 (non-Runes mode).

Breaking Changes

  • update Time.svelte to use Runes
  • update svelteTime action to use Runes
  • update TypeScript definitions to replace deprecated SvelteComponentTyped with Component

1.0.0 - 2025-01-23

Features

  • establish a stable release before upgrading to Svelte 5

Fixes

  • upgrade dayjs to v1.11.13

0.9.0 - 2024-04-19

Features

  • allow title attribute to be overridden

0.8.2 - 2023-12-16

Fixes

  • fix exports in package.json to include types; add exports for ./src/*.svelte and ./src/*

0.8.1 - 2023-12-16

Fixes

  • add exports to package.json to resolve Vite development warnings

0.8.0 - 2023-07-27

Breaking Changes

  • minimum Svelte version required is 3.55

Features

  • update type definitions to support Svelte 4
  • upgrade dayjs to v1.11.9

0.7.2 - 2023-06-04

  • upgrade dayjs to v1.11.8
  • fix Time.svelte types to allow data-* attributes (e.g., data-test-id)

0.7.1 - 2022-06-18

  • use default CJS imports from dayjs instead of ESM
  • upgrade dayjs to v1.11.3
  • fix TypeScript definition for re-exported dayjs function to extend the relativeTime plugin
  • fix svelteTime action to update when using a custom live interval
  • fix svelteTime action to also set the datetime attribute

0.7.0 - 2022-05-15

  • format title attribute using format prop when using relative time

0.6.3 - 2022-05-15

  • revert back to using ESM exports from dayjs

0.6.2 - 2022-05-15

  • use default CJS imports from dayjs instead of ESM

0.6.1 - 2021-12-16

  • set type="module" in package.json

0.6.0 - 2021-10-10

  • extend TimeProps in svelte-time.d.ts SvelteTimeOptions interface

0.5.0 - 2021-09-15

  • Use .svelte.d.ts extension for component TypeScript definition

0.4.2 - 2021-09-01

  • Update documentation on exported dayjs function

0.4.1 - 2021-08-24

  • Fix live prop value in README.md
  • Add example set-ups (SvelteKit, Vite, Sapper, Rollup, Webpack)

0.4.0 - 2021-07-27

  • Export dayjs from src/index.js

0.3.1 - 2021-07-27

  • Add TypeScript definition for svelte-time/src/dayjs export

0.3.0 - 2021-03-02

  • Forward $$restProps to the time element

0.2.0 - 2021-02-28

  • Add live prop to update a relative timestamp at an interval

0.1.0 - 2021-02-27

  • Initial release