{"id":13531731,"url":"https://github.com/marcreichel/alpine-timeago","last_synced_at":"2025-08-20T01:31:25.187Z","repository":{"id":37701837,"uuid":"470476049","full_name":"marcreichel/alpine-timeago","owner":"marcreichel","description":"Simple Alpine.js plugin to display the human-readable distance between a date and now.","archived":false,"fork":false,"pushed_at":"2024-05-29T14:09:07.000Z","size":163,"stargazers_count":71,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-11T12:11:38.619Z","etag":null,"topics":["alpine-js","alpinejs","date","datetime","difference","hacktoberfest","human-readable-timespans","plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/marcreichel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"publiccode":null,"codemeta":null},"funding":{"github":["marcreichel"]}},"created_at":"2022-03-16T07:28:49.000Z","updated_at":"2024-10-11T08:47:52.000Z","dependencies_parsed_at":"2024-05-29T16:27:36.051Z","dependency_job_id":"fd7ae00d-bb3d-47d5-95f3-d392c8a87d38","html_url":"https://github.com/marcreichel/alpine-timeago","commit_stats":{"total_commits":31,"total_committers":2,"mean_commits":15.5,"dds":0.09677419354838712,"last_synced_commit":"130c7db053627d960ce77b972c7debda49fbb08e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcreichel%2Falpine-timeago","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcreichel%2Falpine-timeago/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcreichel%2Falpine-timeago/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcreichel%2Falpine-timeago/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcreichel","download_url":"https://codeload.github.com/marcreichel/alpine-timeago/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230382858,"owners_count":18216854,"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":["alpine-js","alpinejs","date","datetime","difference","hacktoberfest","human-readable-timespans","plugin"],"created_at":"2024-08-01T07:01:05.222Z","updated_at":"2024-12-19T05:07:31.943Z","avatar_url":"https://github.com/marcreichel.png","language":"JavaScript","funding_links":["https://github.com/sponsors/marcreichel"],"categories":["Extensions \u0026 Plugins"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e⏱ Alpine TimeAgo ⏱\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  An \u003ca href=\"https://alpinejs.dev\"\u003eAlpine.js\u003c/a\u003e plugin to return the distance between a given date and now in words (like \"3 months ago\", \"about 2 hours ago\" or \"in about 5 hours\").\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@marcreichel/alpine-timeago\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/tag/marcreichel/alpine-timeago?label=version\" alt=\"version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@marcreichel/alpine-timeago\"\u003e\n    \u003cimg src=\"https://img.badgesize.io/marcreichel/alpine-timeago/main/dist/alpine-timeago.min.js.svg?compression=gzip\u0026color=green\" alt=\"Build size\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@marcreichel/alpine-timeago\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dt/@marcreichel/alpine-timeago\" alt=\"downloads\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.jsdelivr.com/package/npm/@marcreichel/alpine-timeago\"\u003e\n    \u003cimg src=\"https://data.jsdelivr.com/v1/package/npm/@marcreichel/alpine-timeago/badge?style=rounded\" alt=\"JSDelivr\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@marcreichel/alpine-timeago\"\u003e\n    \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/marcreichel/alpine-timeago\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://gitmoji.dev/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg\" alt=\"Gitmoji\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## 🚀 Installation\n\n### CDN\n\nInclude the following `\u003cscript\u003e` tag in the `\u003chead\u003e` of your document, just before Alpine.\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@marcreichel/alpine-timeago@latest/dist/alpine-timeago.min.js\" defer\u003e\u003c/script\u003e\n```\n\n### NPM\n\n```shell\nnpm install @marcreichel/alpine-timeago\n```\n\nAdd the `x-timeago` directive to your project by importing the package **before** starting Alpine.\n\n```js\nimport Alpine from 'alpinejs';\nimport TimeAgo from '@marcreichel/alpine-timeago';\n\nAlpine.plugin(TimeAgo);\n\nAlpine.start();\n```\n\n## 🪄 Usage\n\n### Directive\n\nTo convert a Date to the human-readable distance from now, add the `x-data` and `x-timeago` directives to an element and\npass the date (as a `Date` or a string in ISO format) to the `x-timeago` directive. The directive will update the output\nevery 30 seconds.\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\" x-timeago=\"date\"\u003e\u003c/span\u003e\n```\n\nUnder the hood the directive is using [`formatDistanceToNow`](https://date-fns.org/v2.28.0/docs/formatDistanceToNow)\nfrom `date-fns`.\n\n#### No suffix\n\nIf you do not want the \"[diff] ago\" suffix or \"in [diff]\" prefix, you can use the `x-timeago.pure` modifier.\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\" x-timeago.pure=\"date\"\u003e\u003c/span\u003e\n```\n\n#### Include seconds\n\nDistances less than a minute are more detailed.\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\" x-timeago.seconds=\"date\"\u003e\u003c/span\u003e\n```\n\n### Strict\n\nIf you do not want the \"about [diff]\" or \"less than [diff]\" prefixes, you can use the `x-timeago.strict` modifier.\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\" x-timeago.strict=\"date\"\u003e\u003c/span\u003e\n```\n\n#### Strict options\n\nThe strict mode comes with its own set of modifiers for controlling the output.\n\n##### Force unit\n\nUse the `x-timeago.strict.unit.[unit]` modifier with one of the following units to force the unit in the output.\n\n- `second` (e.g. `x-timeago.strict.unit.second`)\n- `minute` (e.g. `x-timeago.strict.unit.minute`)\n- `hour` (e.g. `x-timeago.strict.unit.hour`)\n- `day` (e.g. `x-timeago.strict.unit.day`)\n- `month` (e.g. `x-timeago.strict.unit.month`)\n- `year` (e.g. `x-timeago.strict.unit.year`)\n\n##### Adjust rounding method\n\nBy default, the values are rounded using the `Math.round` algorithm. If you would like to adjust this, use\nthe `x-timeago.rounding.[method]` modifier with one of the following methods:\n\n- `floor` (e.g. `x-timeago.strict.rounding.floor`)\n- `ceil` (e.g. `x-timeago.strict.rounding.ceil`)\n- `floor` (e.g. `x-timeago.strict.rounding.round`)\n\n### Magic function\n\nAs of version 1.3.0 of this package a `$timeago` magic function is included which will return the human-readable\ndistance from now.\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\" x-text=\"$timeago(date)\"\u003e\u003c/span\u003e\n```\n\n\u003e **Note**: Using the magic function the distance does not get updated automatically. You have to update it yourself if\n\u003e you want to.\n\n#### No suffix\n\nIf you do not want the \"[diff] ago\" suffix or \"in [diff]\" prefix, you can provide `true` as the second parameter to the\nfunction.\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\" x-text=\"$timeago(date, true)\"\u003e\u003c/span\u003e\n```\n\n#### Include seconds\n\nIf you want distances less than a minute to be more detailed, you can provide `true` as the third parameter to the\nfunction.\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\" x-text=\"$timeago(date, null, true)\"\u003e\u003c/span\u003e\n```\n\n#### Strict\n\nIf you do not want the \"about [diff]\" or \"less than [diff]\" prefixes, you can use the fourth parameter to provide the \"\nstrict\" options.\n\n##### Default\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\"\n      x-text=\"$timeago(date, null, null, { strict: true })\"\u003e\u003c/span\u003e\n```\n\n##### Unit\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\"\n      x-text=\"$timeago(date, null, null, { strict: true, unit: 'second' })\"\u003e\u003c/span\u003e\n```\n\n##### Rounding method\n\n```html\n\u003cspan x-data=\"{ date: new Date() }\"\n      x-text=\"$timeago(date, null, null, { strict: true, roundingMethod: 'floor' })\"\u003e\u003c/span\u003e\n```\n\n### Other locales\n\nIf you are using the `npm` installation method for this package or the ESM distribution, you can use the\n`TimeAgo.configure()` method to provide a different locale from `date-fns`.\n\n```javascript\nimport TimeAgo from '@marcreichel/alpine-timeago';\nimport {de} from 'date-fns/locale';\n\nAlpine.plugin(TimeAgo.configure({\n    locale: de,\n}));\n```\n\n## 📄 License\n\nCopyright (c) 2022 Marc Reichel and contributors.\n\nLicensed under the MIT license, see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcreichel%2Falpine-timeago","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcreichel%2Falpine-timeago","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcreichel%2Falpine-timeago/lists"}