relative_time

A Flutter package to express a DateTime object relative to the current time in text form. For instance, it may transform DateTimes into 3 years ago, or in 42 minutes, or now.

Features

  • Available in more languages than you can imagine.
  • Provides localization delegate for easy internationalization.
  • Usable as class instance method call or extension method.
  • Can be expressed in different, customizable time units.

Getting started

The package may optionally retrieve the appropriate localization from the BuildContext. The standard way to setup localization is to make use of a WidgetApp's (such as a MaterialApp) localizationsDelegates and supportedLocales. If you're already using these to localize your app, it should suffice to add RelativeTimeLocalizations.delegate to your list of localizationsDelegates, roughly as follows.

MaterialApp(
  localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
    AppLocalizations.delegate,
    RelativeTimeLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
  ],
  supportedLocales: AppLocalizations.supportedLocales,
);

If your app does not make use of (this form of) localization yet but you would like it to, reference the Flutter documentation on internationalization for more information on how to set this up.

Usage

The relative time may be accessed by passing the DateTime source object to format on an instance of RelativeTime with either a BuildContext (if configured for localization) or a specific Locale.

RelativeTime(context: context).format(time);
RelativeTime(locale: const Locale('en')).format(time);

Alternatively, the provided DateTime extension method is a bit more concise.

time.relativeTime(context: context);
time.relativeTime(locale: const Locale('en'));

You may specify a list of time units that will be considered. This can be any of the following: year, quarter, month, week, day, hour, minute and second. By default, all time units except quarter are potentially used. The following limits the relative time to being expressed in quarters and weeks. No judgement here. It is recommended though to include a more granular unit than weeks for most practical use cases, because anything less than one week would otherwise be rounded down to now.

RelativeTime(
  context: context, 
  timeUnits: const <TimeUnit>[
    TimeUnit.quarter,
    TimeUnit.week,
  ],
).format(time);

Testing

The current time may be mocked with help from the clock package.

withClock(
  Clock.fixed(DateTime.fromMicrosecondsSinceEpoch(0)),
  () => RelativeTime(context: context).format(time),
);

Additional information

Translations have been extracted from the Unicode CLDR Project. The extraction tool for this purpose is available in the dev folder. Note that due to the automated nature of this process, PRs for language updates will not be considered.

Libraries

relative_time
Formats a DateTime as relative time.