Moving Away From Primer::LocalTime

This guide will show you how to upgrade from the now deprecated Primer::LocalTime component to the latest Primer::Beta::RelativeTime component.

A Migration Example

The most common use case of the LocalTime component can be migrated with only a few minor changes.

For example, if the LocalTime was set up in this way:

<%= Primer::LocalTime(datetime:, initial_text: %>

It can be migrated by removing initial_text, setting an empty prefix, and adding threshold: "PT0S".

<%= Primer::Beta::RelativeTime(datetime:, prefix: "", threshold: "PT0S") %>

The RelativeTime component defaults to the iso8601 format and does not need to be specified directly.

The threshold value is an ISO-8601 "duration" that tells the RelativeTime component to display the absolute date/time, instead of relative time description. The example of PT0S says to switch to absolute time display starting zero (0) seconds ago. In practice, this means it will always display the absolute time. With the LocalTime component, PT0S was the default threshold. The RelativeTime component defaults to P30D, however, and it will need to be zeroed out to always display a datetime.


The following arguments are different between LocalTime and RelativeTime.

From Primer::LocalTimeTo Primer::Beta::RelativeTimeNotes
initial_textn/aNo longer used.
n/atenseWhich tense to use. One of :auto, :future, or :past.
n/aprefixWhat to prefix the relative ime display with.
n/athresholdThe threshold, in ISO-8601 'durations' format, at which relative time displays become absolute.
n/aprecisionThe precision elapsed time should display. One of nil, :day, :hour, :minute, :month, :second, or :year.
n/aformatThe format the display should take. One of :auto, :elapsed, or :micro.
n/alangThe language to use.
n/atitleProvide a custom title to the element.

The remaining arguments stayed the same.

Please see the following documentation for complete descriptions and examples.


Back to development docs