Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marcreichel/alpine-timeago
Simple Alpine.js plugin to display the human-readable distance between a date and now.
https://github.com/marcreichel/alpine-timeago
alpine-js alpinejs date datetime difference hacktoberfest human-readable-timespans plugin
Last synced: 5 days ago
JSON representation
Simple Alpine.js plugin to display the human-readable distance between a date and now.
- Host: GitHub
- URL: https://github.com/marcreichel/alpine-timeago
- Owner: marcreichel
- License: mit
- Created: 2022-03-16T07:28:49.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-29T14:09:07.000Z (6 months ago)
- Last Synced: 2024-10-11T12:11:38.619Z (about 1 month ago)
- Topics: alpine-js, alpinejs, date, datetime, difference, hacktoberfest, human-readable-timespans, plugin
- Language: JavaScript
- Homepage:
- Size: 159 KB
- Stars: 71
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome - Alpine Timeago - Display the human-readable distance between a date and now
README
⏱ Alpine TimeAgo ⏱
An Alpine.js 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").
## 🚀 Installation
### CDN
Include the following `` tag in the `<head>` of your document, just before Alpine.
```html
<script src="https://cdn.jsdelivr.net/npm/@marcreichel/alpine-timeago@latest/dist/alpine-timeago.min.js" defer>
```
### NPM
```shell
npm install @marcreichel/alpine-timeago
```
Add the `x-timeago` directive to your project by importing the package **before** starting Alpine.
```js
import Alpine from 'alpinejs';
import TimeAgo from '@marcreichel/alpine-timeago';
Alpine.plugin(TimeAgo);
Alpine.start();
```
## 🪄 Usage
### Directive
To convert a Date to the human-readable distance from now, add the `x-data` and `x-timeago` directives to an element and
pass the date (as a `Date` or a string in ISO format) to the `x-timeago` directive. The directive will update the output
every 30 seconds.
```html
```
Under the hood the directive is using [`formatDistanceToNow`](https://date-fns.org/v2.28.0/docs/formatDistanceToNow)
from `date-fns`.
#### No suffix
If you do not want the "[diff] ago" suffix or "in [diff]" prefix, you can use the `x-timeago.pure` modifier.
```html
```
#### Include seconds
Distances less than a minute are more detailed.
```html
```
### Strict
If you do not want the "about [diff]" or "less than [diff]" prefixes, you can use the `x-timeago.strict` modifier.
```html
```
#### Strict options
The strict mode comes with its own set of modifiers for controlling the output.
##### Force unit
Use the `x-timeago.strict.unit.[unit]` modifier with one of the following units to force the unit in the output.
- `second` (e.g. `x-timeago.strict.unit.second`)
- `minute` (e.g. `x-timeago.strict.unit.minute`)
- `hour` (e.g. `x-timeago.strict.unit.hour`)
- `day` (e.g. `x-timeago.strict.unit.day`)
- `month` (e.g. `x-timeago.strict.unit.month`)
- `year` (e.g. `x-timeago.strict.unit.year`)
##### Adjust rounding method
By default, the values are rounded using the `Math.round` algorithm. If you would like to adjust this, use
the `x-timeago.rounding.[method]` modifier with one of the following methods:
- `floor` (e.g. `x-timeago.strict.rounding.floor`)
- `ceil` (e.g. `x-timeago.strict.rounding.ceil`)
- `floor` (e.g. `x-timeago.strict.rounding.round`)
### Magic function
As of version 1.3.0 of this package a `$timeago` magic function is included which will return the human-readable
distance from now.
```html
```
> **Note**: Using the magic function the distance does not get updated automatically. You have to update it yourself if
> you want to.
#### No suffix
If you do not want the "[diff] ago" suffix or "in [diff]" prefix, you can provide `true` as the second parameter to the
function.
```html
```
#### Include seconds
If you want distances less than a minute to be more detailed, you can provide `true` as the third parameter to the
function.
```html
```
#### Strict
If you do not want the "about [diff]" or "less than [diff]" prefixes, you can use the fourth parameter to provide the "
strict" options.
##### Default
```html
```
##### Unit
```html
```
##### Rounding method
```html
```
### Other locales
If you are using the `npm` installation method for this package or the ESM distribution, you can use the
`TimeAgo.configure()` method to provide a different locale from `date-fns`.
```javascript
import TimeAgo from '@marcreichel/alpine-timeago';
import {de} from 'date-fns/locale';
Alpine.plugin(TimeAgo.configure({
locale: de,
}));
```
## 📄 License
Copyright (c) 2022 Marc Reichel and contributors.
Licensed under the MIT license, see [LICENSE](LICENSE) for details.