A Guide to Formatting Dates with toLocaleDateString in JavaScript

javascript date calendar

When building web applications, dates are a fundamental part of the user experience. From displaying due dates to event schedules, how you format dates can significantly impact how users interpret and interact with your application.

In this post, I’ll explore toLocaleDateString() — which is a flexible method that allows you to format dates in a user-friendly and locale-aware way.

Introduction

The toLocaleDateString() is a method of the JavaScript Date object that returns a string with a date formatted according to the specified locale or the default locale of the runtime environment.

By default, it formats dates based on the browser or system’s locale settings. However, you can specify a locale and options to customize the output.

A default formatting with no specified locale and option:

const ISOString = '2025-01-15T10:00:00Z';
const date = new Date(ISOString);

// Default formatting
console.log(date.toLocaleDateString());

// Output (depends on your environment): "1/15/2025" (US) or "15/01/2025" (UK)

The default format depends on your browser or system's locale.

In the event you want more control, that’s where specifying locales comes in.

Formatting for different locales

The first parameter of toLocaleDateString() is the locale string — which would be en-US for American English, en-GB for British English, or ja-JP for Japanese.

const ISOString = '2025-01-15T10:00:00Z';
const date = new Date(ISOString);

// US format (MM/DD/YYYY)
console.log(date.toLocaleDateString('en-US')); // Output: "1/15/2025"

// British format (DD/MM/YYYY)
console.log(date.toLocaleDateString('en-GB')); // Output: "15/01/2025"

// Japanese format (YYYY/MM/DD)
console.log(date.toLocaleDateString('ja-JP')); // Output: "2025/01/15"

Locales ensure that dates are displayed in a format familiar to the user, improving usability and accessibility.

Customizing the Date Format

The toLocaleDateString() method accepts an options object as its second parameter. This allows you to control which parts of the date are displayed and how.

Here’s an example of customizing the format:

const ISOString = '2025-01-15T10:00:00Z';
const date = new Date(ISOString);

/**
 * Long format.
 * Output: "Wednesday, January 15, 2025"
 */
console.log(
  date.toLocaleDateString('en-US', {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  })
);

/**
 * Short format.
 * Output: "01/15/25"
 */
console.log(
  date.toLocaleDateString('en-US', {
    year: '2-digit',
    month: '2-digit',
    day: '2-digit',
  })
);

The options Object: Key Properties

Here are some useful properties you can use in the options object:

• weekday: Specifies the day of the week. Options: 'narrow', 'short', 'long'.

  { weekday: 'narrow' } // "W"
  { weekday: 'short' } // "Wed"
  { weekday: 'long' } // "Wednesday"

• year: Specifies the year format. Options: 'numeric', '2-digit'.

  { year: 'numeric' } // "2025"
  { year: '2-digit' } // "25"

• month: Specifies the month format. Options: 'numeric', '2-digit', 'narrow', 'short', 'long'.

  { month: 'numeric' } // "1"
  { month: '2-digit' } // "01"
  { month: 'narrow' } // "J"
  { month: 'short' } // "Jan"
  { month: 'long' } // "January"

• day: Specifies the day of the month. Options: 'numeric', '2-digit'.

  { day: 'numeric' } // "15"
  { day: '2-digit' } // "15"

You can mix and match these options to create custom formats.

Conclusion

JavaScript’s toLocaleDateString() method is a powerful and flexible tool for formatting dates in human-readable, locale-aware ways, whether you’re building an app or just want to make your date displays more user friendly.