Components

Timeago

GitHub

A Stimulus controller that returns the distance between the given date and now in words.

Installation

  1. Install the package

    Terminal
    $ yarn add @stimulus-components/timeago

  2. Register the controller in your application

    app/javascript/controllers/index.js
    import { Application } from '@hotwired/stimulus'
import Timeago from '@stimulus-components/timeago'

const application = Application.start()
application.register('timeago', Timeago)

This component is based on the date-fns/formatDistanceToNow.

Example

Timeago

Stimulus 1.0.0 was released .

Usage

app/views/index.html
<p>
  Stimulus 1.0.0 was released
  <time data-controller="timeago" data-timeago-datetime-value="2018-01-30T09:00"></time>.
</p>

Configuration

AttributeDefaultDescriptionOptional
data-timeago-datetime-valueundefinedString that can be parsed by Date.parse().❌
data-timeago-refresh-interval-valueundefinedInterval in milliseconds to reload the distance.✅
data-timeago-include-seconds-valuefalseDistances less than a minute are more detailed✅
data-timeago-add-suffix-valuefalseResult specifies if now is earlier or later than the passed date✅

includeSeconds and addSuffix are the options of the date-fns/formatDistanceToNow method.

If the datetime string passed via data-timeago-datetime-value is not parseable by Date.parse() it will display the given value instead.

Bonus

If you're using Rails, you can define this helper:

app/helpers/application_helper.rb
def timeago(date, format: :long)
  return if date.blank?

  content = I18n.l(date, format: format)

  tag.time(content,
            title: content,
            data: {
              controller: 'timeago',
              timeago_datetime_value: date.iso8601
            })
end

And use it in your html:

app/views/index.html.erb
<p>Created <%= timeago(@project.created_at) %></p>

Extending Controller

You can use inheritance to extend the functionality of any Stimulus component:

app/javascript/controllers/timeago_controller.js
import Timeago from "stimulus-timeago"
import { fr } from "date-fns/locale"

export default class extends Timeago {
  connect() {
    super.connect()
    console.log("Do what you want here.")
  }

  // You can override this getter to change the locale.
  // Don't forget to import it.
  get locale() {
    return fr
  }
}

This controller will automatically have access to targets defined in the parent class.

If you override the connect, disconnect or any other methods from the parent, you'll want to call super.method() to make sure the parent functionality is executed.