Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/metonym/svelte-time
Svelte component and action to format a timestamp using day.js
https://github.com/metonym/svelte-time
ago dayjs relative svelte svelte-action svelte-component time-formatting timestamp
Last synced: 3 days ago
JSON representation
Svelte component and action to format a timestamp using day.js
- Host: GitHub
- URL: https://github.com/metonym/svelte-time
- Owner: metonym
- License: mit
- Created: 2021-02-27T22:52:40.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-07T19:56:35.000Z (10 months ago)
- Last Synced: 2024-04-07T22:24:40.213Z (10 months ago)
- Topics: ago, dayjs, relative, svelte, svelte-action, svelte-component, time-formatting, timestamp
- Language: TypeScript
- Homepage: https://metonym.github.io/svelte-time
- Size: 1.01 MB
- Stars: 126
- Watchers: 3
- Forks: 7
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# svelte-time
[![NPM][npm]][npm-url]
`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](https://github.com/iamkun/dayjs), a lightweight date-time library.
```svelte no-eval
```
Try it in the [Svelte REPL](https://svelte.dev/repl/00b3877edb80425b96bb41fb18059882).
---
## Installation
```bash
# npm
npm i -D svelte-time
# pnpm
pnpm i -D svelte-time dayjs
# Bun
bun i -D svelte-time
# Yarn
yarn add -D svelte-time
```
Note that [pnpm](https://github.com/pnpm/pnpm) users must also install `dayjs`.
## Usage
### `Time` component
The displayed time defaults to `new Date().toISOString()` and is formatted as `"MMM DD, YYYY"`.
```svelte
import Time from "svelte-time";
```
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](https://day.js.org/docs/en/display/format) for acceptable formats.
```svelte
```
### Relative time
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](https://day.js.org/docs/en/display/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
```
### Live updates
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
```
### `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.
```svelte
import { svelteTime } from "svelte-time";
```
#### Relative time
Set `relative` to `true` to use relative time.
```svelte
```
To customize or omit the `title` attribute, use the `title` prop.
```svelte
```
Similar to the `Time` component, the `live` prop only works with relative time.
```svelte
```
Specify a custom update interval using the `live` prop.
```svelte
```
### `dayjs` export
The `dayjs` library is exported from this package for your convenience.
**Note**: the exported `dayjs` function already extends the [relativeTime plugin](https://day.js.org/docs/en/plugin/relative-time).
```svelte
import { dayjs } from "svelte-time";
let timestamp = "";
(timestamp = dayjs().format("HH:mm:ss.SSSSSS"))}>
Update {timestamp}
```
### Custom locale
The default `dayjs` locale is English. No other locale is loaded by default for performance reasons.
To use a [custome locale](https://day.js.org/docs/en/i18n/changing-locale), import the relevant language from `dayjs`. See a list of [supported locales](https://github.com/iamkun/dayjs/tree/dev/src/locale).
```svelte
import "dayjs/locale/de"; // German locale
import Time, { dayjs } from "svelte-time";
```
### Custom locale (global)
Use the [`dayjs.locale`](https://day.js.org/docs/en/i18n/changing-locale) method to set a custom locale as the default.
```svelte no-eval
import "dayjs/locale/de"; // German locale
import { dayjs } from "svelte-time";
// Set the default locale to German.
dayjs.locale("de");
```
### Custom timezone
To use a [custom timezone](https://day.js.org/docs/en/timezone/timezone), import the `utc` and `timezone` plugins from `dayjs`.
```svelte no-eval
import utc from "dayjs/plugin/utc";
import timezone from "dayjs/plugin/timezone";
import Time, { dayjs } from "svelte-time";
dayjs.extend(utc);
dayjs.extend(timezone);
```
### Custom timezone (global)
Use the [`dayjs.tz.setDefault`](https://day.js.org/docs/en/timezone/default-timezone) method to set a custom timezone as the default.
```svelte no-eval
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");
```
### User timezone
Use the [`dayjs.ts.guess`](https://day.js.org/docs/en/timezone/guessing-user-timezone) 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`](https://day.js.org/docs/en/plugin/advanced-format) 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`](https://day.js.org/docs/en/manipulate/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
### Props
| Name | Type | Default value |
| :-------- | :---------------------------------------------------- | :--------------------------------------------------------------------------------------- |
| timestamp | `string` | `number` | `Date` | `Dayjs` | `new Date().toISOString()` |
| format | `string` | `"MMM DD, YYYY"` (See [dayjs display format](https://day.js.org/docs/en/display/format)) |
| relative | `boolean` | `false` |
| live | `boolean` | `number` | `false` |
| formatted | `string` | `""` |
## Examples
- [examples/sveltekit](examples/sveltekit)
- [examples/vite](examples/vite)
- [examples/rollup](examples/rollup)
- [examples/webpack](examples/webpack)
## Changelog
[CHANGELOG.md](CHANGELOG.md)
## License
[MIT](LICENSE)
[npm]: https://img.shields.io/npm/v/svelte-time.svg?style=for-the-badge&color=%23ff3e00
[npm-url]: https://npmjs.com/package/svelte-time