kalvn logo kalvn

Format a date in JavaScript without a library

Written on
March 2, 2025
·
3 minutes
read

This morning I came across this article detailing the use of the Date object's toLocaleDateString, toLocaleTimeString and toLocaleString methods to display a date in a format that is easy for humans to read, while adapting to their regional preferences.

Since date management is notoriously difficult in JavaScript, I've looked into the possibilities offered by native objects and have always tended to rely on external libraries instead, date-fns being the one I like the most.

However, if there's one area in which native objects excel in comparison to external libs, it is localisation. In other words, adjusting the display of a value according to the user's regional settings.

A web browser comes standard with translations for every conceivable langue, and JavaScript is no exception.

On the other hand, if it needs to support multiple languages, a library will have to be supplied with its own language pack that it needs to ship to your users, hence increasing the amount of code they have to download. It is especially true if your website supports dynamic language switching.

So before considering using an external library, it is a good idea the check if there isn't already a native solution to the problem.

Date.toLocaleString and its derivatives

The native Date object has 3 methods for locale display:

I'll focus on the third one as it combines the other two. But they work in a similar way.

Adapting to a particular language or country

To display the date and time that correspond to the language in which the user is browsing:

console.log(new Date().toLocaleString());

The result will depend on your regional settings.

To force a language or locale:

// German format :
console.log(new Date().toLocaleString('de'));
// 2.3.2025, 09:24:37

// English format for USA :
console.log(new Date().toLocaleString('en-US'));
// 3/2/2025, 9:24:37 AM

// English format for UK :
console.log(new Date().toLocaleString('en-GB'));
// 02/03/2025, 09:24:37

This first parameter is rather flexible. It handles either:

Choose fields to display

On top of language or locale selection, it is possible to configure which field to show and what their format should be. Example:

console.log(new Date().toLocaleString('de', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
}));
// Sonntag, 2. März 2025

It is also possible to choose between 12 hours and 24 hours formats:

console.log(new Date().toLocaleString('en-US', {
  hour12: false
}));
// 3/2/2025, 15:25:34

Choose your timezone

In some cases, it can be useful to select a timezone which differs from the one of the execution context:

// Date and time with the american format but with Australia's timezone:
console.log(new Date().toLocaleString('en-US', {
  timeZone: 'Australia/Sydney'
}));
// 3/2/2025, 7:27:34 PM

To display explicitly the timezone in the result, the option timeZoneName can be used:

console.log(new Date().toLocaleString('en-US', {
  timeZone: 'Australia/Sydney',
  timeZoneName: 'short'
}));
// 3/2/2025, 7:27:57 PM GMT+11

There are many more options to be used, take time to review them.

If your use case requires more fine-grained customisation, and as the new Temporal API is not yet available everywhere, it is generally preferable to use an external library.