svelte-time

[![NPM][npm]][npm-url]

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.

``svelte





a few seconds ago

`

Try it in the Svelte REPL.

---

Installation

`bash


npm

npm i svelte-time

pnpm

pnpm i svelte-time

Bun

bun i svelte-time

Yarn

yarn add svelte-time
`

Usage

$3

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

`svelte



`

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

`svelte



`

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

`svelte



`

$3

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

`svelte



`

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

Use the format prop to customize the format.

`svelte

`

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

`svelte

`

Set the value to undefined to omit the title altogether.

`svelte

`

$3

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

`svelte

`

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

`svelte




60 1_000} relative />
`

$3

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.

`svelte


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

#### Relative time

Set relative to true to use relative time.

`svelte
use:svelteTime={{
relative: true,
timestamp: "2021-02-02",
}}
>

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

#### Locale

Use the locale prop to format timestamps in different languages. Make sure to import the locale from dayjs first.

`svelte


use:svelteTime={{
timestamp: "2024-01-01",
format: "dddd, MMMM D, YYYY",
locale: "de",
}}
>

use:svelteTime={{
relative: true,
timestamp: "2024-01-01",
locale: "es",
}}
>
`

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

`svelte
use:svelteTime={{
relative: true,
title: "Custom title",
timestamp: "2021-02-02",
}}
>

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

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

`svelte
use:svelteTime={{
relative: true,
live: true,
}}
>
`

Specify a custom update interval using the live prop.

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

$3

Set withoutSuffix to true to remove the "ago" suffix from relative time.

`svelte















`

This also works with the svelteTime action:

`svelte
use:svelteTime={{
relative: true,
timestamp: "2021-02-02",
withoutSuffix: true,
}}
>
`

$3

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

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

`svelte


(timestamp = dayjs().format("HH:mm:ss.SSSSSS"))}>
Update {timestamp}

`

$3

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

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

`svelte






`

The Locales type is exported for TypeScript usage.

`typescript
import type { Locales } from "svelte-time";

const locale: Locales = "de";
const localeStore = writable("en");
`

The locale prop also works with relative time.

`svelte






`

The withoutSuffix prop also works with locales:

`svelte










`

$3

The locale prop is reactive, so you can bind it to a Svelte store to update all instances when the locale changes.

`svelte


setLocale("en")}>English
setLocale("de")}>Deutsch
setLocale("es")}>Español
setLocale("fr")}>Français



`

$3

You can also use the dayjs.locale method to set a custom locale as the default, or pass a dayjs instance with locale already applied.

`svelte



`

To set a global default locale:

`svelte

`

$3

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

`svelte


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

$3

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

`svelte

`

$3

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

`js
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.

`diff
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.

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

API

$3

| Name | Type | Default value |
| :------------ | :---------------------------------------------------- | :--------------------------------------------------------------------------------------- |
| timestamp | string | number | Date | Dayjs | new Date().toISOString() |
| format | string | "MMM DD, YYYY" (See dayjs display format) |
| relative | boolean | false |
| withoutSuffix | boolean | false (only applies when relative is true) |
| live | boolean | number | false |
| locale | Locales (TypeScript) | string | "en" (See supported locales) |
| formatted | string | ""` |

Examples

- examples/sveltekit
- examples/vite
- examples/rollup
- examples/webpack

Changelog

CHANGELOG.md

License

MIT

[npm]: https://img.shields.io/npm/v/svelte-time.svg?style=for-the-badge&color=%23ff3e00
[npm-url]: https://npmjs.com/package/svelte-time