{"id":16791987,"url":"https://github.com/metonym/svelte-time","last_synced_at":"2025-04-06T07:14:51.626Z","repository":{"id":37021888,"uuid":"342975386","full_name":"metonym/svelte-time","owner":"metonym","description":"Svelte component and action to format a timestamp using day.js","archived":false,"fork":false,"pushed_at":"2024-04-07T19:56:35.000Z","size":1055,"stargazers_count":126,"open_issues_count":7,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-07T22:24:40.213Z","etag":null,"topics":["ago","dayjs","relative","svelte","svelte-action","svelte-component","time-formatting","timestamp"],"latest_commit_sha":null,"homepage":"https://metonym.github.io/svelte-time","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metonym.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-02-27T22:52:40.000Z","updated_at":"2024-04-14T18:41:20.765Z","dependencies_parsed_at":"2023-12-26T17:03:07.882Z","dependency_job_id":"76646e67-1408-4c46-b400-f5a5f71ae0d1","html_url":"https://github.com/metonym/svelte-time","commit_stats":{"total_commits":104,"total_committers":2,"mean_commits":52.0,"dds":"0.019230769230769273","last_synced_commit":"bb5bc8f5b6b3c78d047cfb356696c2d6e0bea820"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metonym%2Fsvelte-time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metonym%2Fsvelte-time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metonym%2Fsvelte-time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metonym%2Fsvelte-time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metonym","download_url":"https://codeload.github.com/metonym/svelte-time/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445681,"owners_count":20939961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ago","dayjs","relative","svelte","svelte-action","svelte-component","time-formatting","timestamp"],"created_at":"2024-10-13T08:43:46.063Z","updated_at":"2025-04-06T07:14:51.603Z","avatar_url":"https://github.com/metonym.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# svelte-time\n\n[![NPM][npm]][npm-url]\n\n**Note:** `svelte-time@2.0.0` only supports Svelte 5 in Runes mode.\n\nUse [svelte-time@1.0.0](https://github.com/metonym/svelte-time/tree/v1.0.0) for Svelte 3, 4, and 5 (non-Runes mode).\n\n---\n\n`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.\n\nUnder the hood, it uses [day.js](https://github.com/iamkun/dayjs), a lightweight date-time library.\n\n```svelte\n\u003c!-- Input --\u003e\n\u003cTime relative /\u003e\n\n\u003c!-- Output rendered in the DOM --\u003e\n\u003ctime title=\"May 15, 2022\" datetime=\"2022-05-15T18:03:57.430Z\"\u003e\n  a few seconds ago\n\u003c/time\u003e\n```\n\nTry it in the [Svelte REPL](https://svelte.dev/playground/e2a27786f93d42878388de482de403c9).\n\n---\n\n## Installation\n\n```bash\n# npm\nnpm i svelte-time\n\n# pnpm\npnpm i svelte-time\n\n# Bun\nbun i svelte-time\n\n# Yarn\nyarn add svelte-time\n```\n\n## Usage\n\n### `Time` component\n\nThe displayed time defaults to `new Date().toISOString()` and is formatted as `\"MMM DD, YYYY\"`.\n\n\u003c!-- render:Basic --\u003e\n\n```svelte\n\u003cscript\u003e\n  import Time from \"svelte-time\";\n\u003c/script\u003e\n\n\u003cTime /\u003e\n```\n\nThe `timestamp` prop can be any of the following `dayjs` values: `string | number | Date | Dayjs`.\n\n\u003c!-- render:CustomTimestamp --\u003e\n\n```svelte\n\u003cTime timestamp=\"2020-02-01\" /\u003e\n\n\u003cTime timestamp={new Date()} /\u003e\n\n\u003cTime timestamp={1e10} /\u003e\n```\n\nUse the `format` prop to format the timestamp. Refer to the [dayjs format documentation](https://day.js.org/docs/en/display/format) for acceptable formats.\n\n\u003c!-- render:CustomFormat --\u003e\n\n```svelte\n\u003cTime timestamp=\"2020-02-01\" format=\"dddd @ h:mm A · MMMM D, YYYY\" /\u003e\n\n\u003cTime timestamp={new Date()} format=\"YYYY/MM/DD\" /\u003e\n\n\u003cTime timestamp={1e10} format=\"ddd\" /\u003e\n```\n\n### Relative time\n\nSet the `relative` prop value to `true` for the relative time displayed in a human-readable format.\n\n\u003c!-- render:RelativeTime --\u003e\n\n```svelte\n\u003cTime relative /\u003e\n\n\u003cTime relative timestamp=\"2021-02-02\" /\u003e\n\n\u003cTime relative timestamp={1e10} /\u003e\n```\n\nWhen using relative time, the `title` attribute will display a formatted timestamp.\n\nUse the `format` prop to customize the [format](https://day.js.org/docs/en/display/format).\n\n\u003c!-- render:RelativeTimeCustomFormat --\u003e\n\n```svelte\n\u003cTime relative format=\"dddd @ h:mm A · MMMM D, YYYY\" /\u003e\n```\n\nWhen using `relative`, the `time` element will set the formatted timestamp as the `title` attribute. Specify a custom `title` to override this.\n\n\u003c!-- render:RelativeTimeCustomTitle --\u003e\n\n```svelte\n\u003cTime relative title=\"Custom title\" /\u003e\n```\n\nSet the value to `undefined` to omit the `title` altogether.\n\n\u003c!-- render:RelativeTimeNoTitle --\u003e\n\n```svelte\n\u003cTime relative title={undefined} /\u003e\n```\n\n### Live updates\n\nSet `live` to `true` for a live updating relative timestamp. The default refresh interval is 60 seconds.\n\n```svelte\n\u003cTime live relative /\u003e\n```\n\nTo customize the interval, pass a value to `live` in milliseconds (ms).\n\n```svelte\n\u003c!-- Update every 30 seconds --\u003e\n\u003cTime live={30 * 1_000} relative /\u003e\n\n\u003c!-- Update every 10 minutes --\u003e\n\u003cTime live={10 * 60 * 1_000} relative /\u003e\n```\n\n### `svelteTime` action\n\nAn alternative to the `Time` component is to use the `svelteTime` action to format a timestamp in a raw HTML element.\n\nThe API is the same as the `Time` component.\n\n\u003c!-- render:SvelteTimeAction --\u003e\n\n```svelte\n\u003cscript\u003e\n  import { svelteTime } from \"svelte-time\";\n\u003c/script\u003e\n\n\u003ctime use:svelteTime\u003e\u003c/time\u003e\n\n\u003ctime\n  use:svelteTime={{\n    timestamp: \"2021-02-02\",\n    format: \"dddd @ h:mm A · MMMM D, YYYY\",\n  }}\n\u003e\u003c/time\u003e\n```\n\n#### Relative time\n\nSet `relative` to `true` to use relative time.\n\n```svelte\n\u003ctime\n  use:svelteTime={{\n    relative: true,\n    timestamp: \"2021-02-02\",\n  }}\n\u003e\u003c/time\u003e\n\n\u003ctime\n  use:svelteTime={{\n    relative: true,\n    timestamp: \"2021-02-02\",\n    format: \"dddd @ h:mm A · MMMM D, YYYY\",\n  }}\n\u003e\u003c/time\u003e\n```\n\nTo customize or omit the `title` attribute, use the `title` prop.\n\n```svelte\n\u003ctime\n  use:svelteTime={{\n    relative: true,\n    title: \"Custom title\",\n    timestamp: \"2021-02-02\",\n  }}\n\u003e\u003c/time\u003e\n\n\u003ctime\n  use:svelteTime={{\n    relative: true,\n    title: undefined,\n    timestamp: \"2021-02-02\",\n  }}\n\u003e\u003c/time\u003e\n```\n\nSimilar to the `Time` component, the `live` prop only works with relative time.\n\n```svelte\n\u003ctime\n  use:svelteTime={{\n    relative: true,\n    live: true,\n  }}\n\u003e\u003c/time\u003e\n```\n\nSpecify a custom update interval using the `live` prop.\n\n```svelte\n\u003ctime\n  use:svelteTime={{\n    relative: true,\n    live: 30 * 1_000, // Update every 30 seconds\n  }}\n\u003e\u003c/time\u003e\n```\n\n### `dayjs` export\n\nThe `dayjs` library is exported from this package for your convenience.\n\n**Note**: the exported `dayjs` function already extends the [relativeTime plugin](https://day.js.org/docs/en/plugin/relative-time).\n\n\u003c!-- render:DayjsExport --\u003e\n\n```svelte\n\u003cscript\u003e\n  import { dayjs } from \"svelte-time\";\n\n  let timestamp = $state(\"\");\n\u003c/script\u003e\n\n\u003cbutton\n  type=\"button\"\n  onclick={() =\u003e (timestamp = dayjs().format(\"HH:mm:ss.SSSSSS\"))}\n\u003e\n  Update {timestamp}\n\u003c/button\u003e\n```\n\n### Custom locale\n\nThe default `dayjs` locale is English. No other locale is loaded by default for performance reasons.\n\nTo 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).\n\n\u003c!-- render:CustomLocale --\u003e\n\n```svelte\n\u003cscript\u003e\n  import \"dayjs/locale/de\"; // German locale\n  import Time, { dayjs } from \"svelte-time\";\n\u003c/script\u003e\n\n\u003cTime timestamp={dayjs().locale(\"de\")} format=\"dddd, MMMM D, YYYY\" /\u003e\n```\n\n### Custom locale (global)\n\nUse the [`dayjs.locale`](https://day.js.org/docs/en/i18n/changing-locale) method to set a custom locale as the default.\n\n```svelte\n\u003cscript\u003e\n  import \"dayjs/locale/de\"; // German locale\n  import { dayjs } from \"svelte-time\";\n\n  // Set the default locale to German.\n  dayjs.locale(\"de\");\n\u003c/script\u003e\n```\n\n### Custom timezone\n\nTo use a [custom timezone](https://day.js.org/docs/en/timezone/timezone), import the `utc` and `timezone` plugins from `dayjs`.\n\n\u003c!-- render:CustomTimezone --\u003e\n\n```svelte\n\u003cscript\u003e\n  import utc from \"dayjs/plugin/utc\";\n  import timezone from \"dayjs/plugin/timezone\";\n\n  import Time, { dayjs } from \"svelte-time\";\n\n  dayjs.extend(utc);\n  dayjs.extend(timezone);\n\u003c/script\u003e\n\n\u003cTime\n  timestamp={dayjs(\"2013-11-18 11:55:20\").tz(\"America/Toronto\")}\n  format=\"YYYY-MM-DDTHH:mm:ss\"\n/\u003e\n```\n\n### Custom timezone (global)\n\nUse the [`dayjs.tz.setDefault`](https://day.js.org/docs/en/timezone/default-timezone) method to set a custom timezone as the default.\n\n```svelte\n\u003cscript\u003e\n  import utc from \"dayjs/plugin/utc\";\n  import timezone from \"dayjs/plugin/timezone\";\n\n  import Time, { dayjs } from \"svelte-time\";\n\n  dayjs.extend(utc);\n  dayjs.extend(timezone);\n  dayjs.tz.setDefault(\"America/New_York\");\n\u003c/script\u003e\n```\n\n### User timezone\n\nUse the [`dayjs.ts.guess`](https://day.js.org/docs/en/timezone/guessing-user-timezone) method to guess the user's timezone.\n\n```js\nimport utc from \"dayjs/plugin/utc\";\nimport timezone from \"dayjs/plugin/timezone\";\n\ndayjs.extend(utc);\ndayjs.extend(timezone);\n\ndayjs.tz.guess(); // America/New_York\n```\n\nTo retrieve the abbreviated time zone, extend the [`advancedFormat`](https://day.js.org/docs/en/plugin/advanced-format) plugin.\n\n```diff\n  import utc from \"dayjs/plugin/utc\";\n  import timezone from \"dayjs/plugin/timezone\";\n+ import advancedFormat from \"dayjs/plugin/advancedFormat\";\n\n  import { dayjs } from \"svelte-time\";\n\n  dayjs.extend(utc);\n  dayjs.extend(timezone);\n+ dayjs.extend(advancedFormat);\n```\n\nThen, 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.\n\n```js\ndayjs().local().format(\"z\"); // EST\ndayjs().local().format(\"zzz\"); // Eastern Standard Time\n```\n\n## API\n\n### Props\n\n| Name      | Type                                                  | Default value                                                                            |\n| :-------- | :---------------------------------------------------- | :--------------------------------------------------------------------------------------- |\n| timestamp | `string` \u0026#124; `number` \u0026#124; `Date` \u0026#124; `Dayjs` | `new Date().toISOString()`                                                               |\n| format    | `string`                                              | `\"MMM DD, YYYY\"` (See [dayjs display format](https://day.js.org/docs/en/display/format)) |\n| relative  | `boolean`                                             | `false`                                                                                  |\n| live      | `boolean` \u0026#124; `number`                             | `false`                                                                                  |\n| formatted | `string`                                              | `\"\"`                                                                                     |\n\n## Examples\n\n- [examples/sveltekit](examples/sveltekit)\n- [examples/vite](examples/vite)\n- [examples/rollup](examples/rollup)\n- [examples/webpack](examples/webpack)\n\n## Changelog\n\n[CHANGELOG.md](CHANGELOG.md)\n\n## License\n\n[MIT](LICENSE)\n\n[npm]: https://img.shields.io/npm/v/svelte-time.svg?style=for-the-badge\u0026color=%23ff3e00\n[npm-url]: https://npmjs.com/package/svelte-time\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetonym%2Fsvelte-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetonym%2Fsvelte-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetonym%2Fsvelte-time/lists"}