Hello and welcome to my post about How to format datetime in Flutter. Each week I will analyse another package published under pub.dev including a working example to implement in your own project. If you want to see the first post of this series head over to How to validate Emails in Flutter.

Date Format

This week’s widget is mandatory if you want to display a certain date or time inside your app. The Date Format package helps you to display time, date, time zone, weekday and some more, regardless of their order. Therefore you have to specify a dateformat string in the code, which determines the format of the desired text of a datetime object. How? Let me show you!

The purpose

Time is important, even in the IT world. No matter if the day of the week is determined in the background, a historization of data needs a timestamp or the user wants to be informed about the exact day and time of an event. Last one needs a visual representation of a datetime object. It is important to decide how date and time should be displayed to the user. Is the event on the 01.August.2021, on the 1.8.21 or on 08/01/21. Possible combinations are a dime a dozen and depending on country and region the user lives. Luckily, the Date Format package provides a solution and allows the conversion of the Datetime object into a readable string.

Package scope

The scope of the package is kept simple and effective. It only allows formatting a datetime object into a text by specifying predefined characters. These characters can read all relevant information from the datetime object and render it as a string. An overview of all characters looks as follows:

yy or yyyy     -> Year
m or mm        -> Number of Month
M or MM        -> String of Month
dd or d        ->  Day
w              ->  week in month
W or WW        ->  week in year
D or DD        ->  weekday
h or hh        ->  hour (0 - 11)
H or HH        ->  hour (0 - 23)
n or nn        ->  minutes
s or ss        ->  seconds
S or SSS       ->  milliseconds
u or uuu       ->  microseconds
am             ->  AM or PM
z or Z         ->  timezone
\\             ->  Escape delimiter

An example

In the accompanying app to this blog series, I have integrated the Date Format Package in such a way that it can display the current time in various formats. In addition to the most important formats according to my opinion, there is also a custom option, where you can try out different formats. Also built in is a CheatSheet to display the possible characters again at a glance.

The formatting itself is quite simple. If you have imported the package you can call the function formatDate. This function gets a datetime object and a datetime_format. Furthermore a locale object is passed, which is used to translate the names for different countries into the respective languages. The parameter is optional and uses English as default.

formatDate(datetime_object, datetime_format, locale_object);

The datetime_format can be a simple string or an array. In both cases the characters (if they are not prefixed with a delimiter) are formatted into the corresponding values, like hours, days, weekday.

The function used in the accompanying app to format the objects looks like the following. The default option represents the custom variant and gets a simple string from a controller for formatting.

The resulting UI looks like in the example video below:

Limitations

During my research I couldn’t find any limitations in this package at first. But while browsing the Github project I became aware of the Locale class. This translates the formatted strings into the respective languages. Unfortunately, at the time of writing this post, only English, Italian, Portuguese, Spanish, Turkish and Vietnamese is supported.

And I noticed another little bug when messing around with the custom option in my app. The developer must have made a little copy paste mistake during programming. When entering the S character, you don’t get the milliseconds, but the seconds. But this is not a big problem and I have already communicated this to the developers as a pull request. You can look this up under Pull Request #24 - Fix millisecond/second Bug when typing S

Installation

Installing the package you can use the flutter command in the command line or simply add the latest version of date_format in your pubspec.yaml under dependencies.

Run this command:

With Dart:

$ dart pub add date_format

With Flutter:

$ flutter pub add date_format

This will add a line like this to your package’s pubspec.yaml (and run an implicit dart pub get):

dependencies:
  date_format: ^2.0.2

Alternatively, your editor might support dart pub get or flutter pub get. Check the docs for your editor to learn more.

Import it

Now in your Dart code, you can use:

import 'package:date_format/date_format.dart';

Version

The latest version at the time of publishing the post is 2.0.2. The newest version supports null safety with Flutter 2. Looking at the history you can see, that the Publisher puts a lot of work into this package to keep it up to date.

Scores

The popularity of the package is the best we have since now: 198 Likes, 130 Pub Points from Flutter, and a Popularity of 98%. I was just a bit surprised about these few likes for such an essential package.

Furthermore, the package supports null safety and all current platforms (Android, IOS, Linux, macOS, Web, Windows). It’s first published in January 2018 and supports null safety since September last year (officially since March this year). It’s under the BDS License. The package provide some basic tests for the package checking essential Date and Time formats. It also has some packages depending on its logic.

Rating

Although the package seems easy to use, it does not quite meet my expectations in a few points. The missing comprehensive tests have led to the mentioned bug in the code. Also, I found out about the locale class just before finishing this post. Here they are missing the responsible documentation and a support for more than just 6 countries. For this reason the package gets only 8 out of 10.

Links

You can find the latest package at pub.dev underdate_format.

If you want to check out the app with every package I wrote about, head over to lucianojung/flutter_package_examples.

If you are curious about the source code of the package visit tejainece/date_format.

Head over to flutter-package-examples.netlify.app to see all the Flutter package examples and try them yourself.