Easily handle dates and times operations in your application using Day.js

Introduction

Working with dates and times in JavaScript can be challenging, especially when specific formats are required. This complexity often leads to inconsistencies in the dates and times within applications. As a result, developers turn to external tools and libraries such as Day.js to manage these operations easily and more accurately.

In this article, we will explore what Day.js is, its basic features, how to use it in your projects, how to extend its functionalities with plugins, and its browser support.

What is Day.js?

Day.js is an easy-to-use lightweight javascript library, designed for handling a wide range of date and time operations, allowing them to be presented in easily readable formats within web applications.

The library can be used on both the client-side(browser) and server-side(Node.Js) environments.

In modern web development, developers seek to prioritize speed and performance when building applications. Large imports and bulky library files are two common hindering factors of these attributes.

Fortunately, Day.js addresses these concerns with a compact file size of just 2KB, making it an ideal choice for managing date and time operations without compromising the application's performance.

Installation

To get started working with the Day.js library in your application, you first need to include it.

To use the library on the client-side, include the following script in the tag of your HTML document.

Alternatively, you can access the library via a CDN such as the jsdeliver CDN.

To install the library as a dependency in your application, run the following command:

npm install dayjs

Next, import dayjs into your javascript file:

import dayjs from 'dayjs';

To create a new Day.js instance, call the dayjs() function. If no argument is passed, it returns an object representing the current date and time:

const currentDate = dayjs();

You can then reference this object to perform various operations on dates and times.

Since Day.js objects are immutable, any operations that would modify the object will return a new instance with the updated date and time.

The ISO DateTime format

To effectively work with dates and times we first need to be familiar with ISO and its DateTime format string.

The ISO (International Organization for Standardization) is a global non-governmental organization that develops and publishes international standards across various industries, ensuring consistency and quality worldwide.

One of the standards provided by ISO is the format for representing dates and times globally.

A typical ISO DateTime format string looks like this:

"2024-12-25T14:30:00.049Z"
// year-month-dayThour:minute:second.millisecondZ

• The T between day and hour acts as a delimiter that separates the date from the time in the string.
• The Z at the end of the string, which stands for Zulu, indicates that the time is in UTC (Coordinated Universal Time).

The native JavaScript Date object offers a toISOString() method, which helps convert a random date into an ISO string.

new Date("may 9 2024").toISOString(); 
// Output: '2024-05-09T23:00:00.000Z'

Now that we understand the ISO DateTime format, let's explore some of the key features of the Day.js library.

Exploring the Key Features of Day.js

The Day.js library comes with a range of features, some of which can be used to format, parse, manipulate, query, and validate dates and times. Let's explore how we can make use of these key features.

Parsing

The parsing feature provides a straightforward way to create a new Day.js object with a specific date and time. This can be done by passing a native JavaScript Date object, a date string, or a Unix timestamp to the dayjs() function.

const date1 = dayjs(new Date()); // called with native Date object.
const date2 = dayjs("2024-08-15"); // called with an ISO date string
const date3 = dayjs(1665613200000); // called with a Unix timestamp

Formatting

The formatting feature allows you to display dates and times in a specific format. The following method is used to perform formatting on dates and times.

• format(): This receives a format string and returns the date and time in that customized format.

const formattedDate = dayjs().format("HH:mm:ss DD-MM-YYYY");
console.log(formattedDate); // '19:57:36 17-08-2024'

Manipulating

The manipulating feature allows you to adjust the dates and times in different ways. This can be done using the following methods.

• add(number, timeUnit): Adds a specified amount of time to the date.

const futureDate = dayjs().add(5, 'days'); // Adds 5 days to the current date
console.log(futureDate.format()); // Returns the added date in an ISO date format

• subtract(number, timeUnit): Subtracts a specified amount of time from the date.

const pastDate = dayjs().subtract(2, 'months');  // Subtracts 2 months from the current date
console.log(pastDate.format()); // Returns the subtracted date in an ISO date format

• startOf(timeUnit): Sets the date to the start of a specific time unit, such as the start of a day, week, month, etc.

const startOfMonth = dayjs().startOf('month'); // Sets the date to the start of the month
console.log(startOfMonth.format()); // Returns the current date from the start of the month in an ISO date format

• endOf(timeUnit): Sets the date to the end of a specific time unit, such as the end of a day, week, month, etc.

const endOfMonth = dayjs().endOf('month'); // Sets the date to the end of the month
console.log(endOfMonth.format()); // Returns the current date from the end of the month in an ISO date format

Querying

The querying feature allows you to check and compare dates and times. This can be done using the following methods which return a boolean value.

• isBefore(date): Checks if the date is before the specified date.

const isBefore = dayjs("2024-08-15").isBefore("2024-09-01");
console.log(isBefore); // true

• isAfter(date): Checks if the date is after the specified date.

const isAfter = dayjs("2024-09-15").isAfter("2024-09-01");
console.log(isAfter); // true

• isSame(date): Checks if the date is the same as the specified date.

const isSame = dayjs("2024-09-01").isSame("2024-09-01");
console.log(isSame); // true

• isBetween(date1, date2): Checks if the date is between two specified dates.

const isBetween = dayjs("2024-09-10").isBetween("2024-09-01", "2024-09-20");
console.log(isBetween); // true

• isLeapYear(): Checks if the year of the date is a leap year.

const isLeapYear = dayjs("2024-02-29").isLeapYear();
console.log(isLeapYear); // true

Validating

The validation feature provides a way to check if the format of the date provided is valid or not. This can be done using the following method:

• isValid(): Returns a boolean value indicating whether a date is correctly parsed.

const validDate = dayjs("2024-02-15").isValid();
console.log(validDate); // true

const invalidDate = dayjs("2024-02-15-456").isValid();
console.log(invalidDate); // false

Extending functionalities with Plugins

The Day.js library offers a variety of independent plugins that can be used to extend its base functionalities. This enables developers to easily perform further complex date and time formatting in their applications.

To use a plugin, you first need to include it and then extend dayjs using the extend() method.

• To include a plugin via CDN:

• To extend dayjs using the plugin:

dayjs.extend(window.dayjs_plugin_pluginName);

• To include and extend a plugin using ES6 syntax:

import calendar from 'dayjs/plugin/pluginName';

dayjs.extend(pluginName);

Now, let's explore how we can use two of the available plugins in an application.

Calendar plugin

The calendar plugin provides a convenient way to display dates and times in a more human-readable format. It is ideal for use in applications such as event reminders, project management, task planners, etc.

Let's take a look at a simple example of how we can use this plugin in an events reminder app.

To get started, we need to include the Day.js library and the calendar plugin via a CDN.

Next, inside our javascript file, we extend dayjs with the calendar plugin and call the dayjs() function to create a new Day.js instance.

dayjs.extend(window.dayjs_plugin_calendar);

const currentDate = dayjs();

The Calendar plugin offers customization options to format how you want the dates and times to be presented. You can define a custom format using an object with the following exact properties:

const customFormat = {
  sameDay: "[Today at] h:mm A",
  nextDay: "[Tomorrow at] h:mm A",
  nextWeek: "[Next] dddd [at] h:mm A",
  lastDay: "[Yesterday at] h:mm A",
  lastWeek: "[Last] dddd [at] h:mm A",
  sameElse: "DD[th of] MMMM YYYY [at] h:mm A",
};

In the object, we escape words in the string values, by wrapping them around [] square brackets.

Using this object, we then display the date and time of the events in the event reminder app:

const eventTimeEl = document.querySelector('.event-time-holder'); // the element to display the event date and time in

const eventDate = "2024-11-26T14:30:00";
// A future date, in ISO date format

eventTimeEl.textContent = dayjs(eventDate).calendar(currentDate, customFormat);

In this example, the eventDate is set to a date months away from the present day. In that case, the date is displayed using the format provided in the sameElse property of the customFormat object.

If the date of the event eventually becomes a past date, such as a day in the previous week, for example:

const eventDate = "2024-08-10T10:30:00";
// a past date in ISO date format

The date is then displayed using the format specified in the lastWeek property of the customFormat object:

RelativeTime plugin

The RelativeTime plugin is a commonly used day.js plugin for displaying date and time differences as relative statements in user interfaces.

The plugin provides 4 different APIs for displaying past and future times:

• .from(date, [withoutSuffix]): Returns a relative time string that describes how far the date being called on is from the provided date. If the withoutSuffix argument is true, it removes the "ago" suffix from the output.

dayjs("2024-08-10").from("2024-11-20");
// Output: '3 months ago'

dayjs("2024-08-10").from("2024-11-20", true);
// Output: '3 months'

• .to(date, [withoutSuffix]): Returns a relative time string that describes how far the provided date is from the date being called on. If the withoutSuffix argument is true, it removes the "in" prefix from the output.

dayjs("2024-08-10").to("2024-11-20");
// Output: 'in 3 months'

dayjs("2024-08-10").to("2024-11-20", true);
// Output: '3 months'

• .fromNow([withoutSuffix]): Returns a relative time string that describes how far the date being called on is from the current date and time. If the withoutSuffix argument is true, it removes the "ago" suffix from the output.

dayjs("2024-08-10").fromNow();
// Output: '8 days ago'

dayjs("2024-08-10").fromNow(true);
// Output: '8 days'

• .toNow([withoutSuffix]): Returns a relative time string that describes how far the current date and time is from the date being called on. If the withoutSuffix argument is true, it removes the "in" prefix from the output.

dayjs("2024-08-10").toNow();
// Output: 'in 8 days'

dayjs("2024-08-10").toNow(true);
// Output: '8 days'

Let's take a look at a simple example of how we can use the RelativeTime plugin to display the timestamp for comments posted in an application's comment section.

As usual, the first step to take is to include the dayjs and the relativeTime plugin as follows:

Then, we extend dayjs with the relativeTime plugin:

dayjs.extend(window.dayjs_plugin_relativeTime);

After that, we can then display the time a comment was posted, in relation to the current Time:

const commentTimeEl = document.querySelector('.comment-time-holder'); // The element to display the comment time in.

const commentPostedTime = '2024-08-15T20:50:00'; // Comment posted time example, in ISO date format.

commentTimeEl.textContent = dayjs(commentPostedTime).fromNow();

At the time the above code was executed, the commentPostedTime variable was set to the current time, which then resulted in the following relative time string output in the comment:

Browser Support and developer popularity

The Day.js library is supported in all modern web browsers. It has an active community with over 19 million NPM downloads.

The library is actively maintained with over 46k github stars and 330 contributors ensuring it remains up-to-date and compatible with the latest JavaScript standards.

Conclusion

In conclusion, utilizing the Day.js library to handle the dates and times operations in your application not only maintains speed and performance but also helps save time by providing ready-to-use functions that can easily be used to format, query, manipulate, parse, and validate dates and times.