JavaScript Intl.DateTimeFormat Guide

Intl.DateTimeFormat provides locale-aware date and time formatting. Here's how to use it effectively.

Basic Usage#

const date = new Date('2024-03-15T14:30:00');

// Default locale
const formatter = new Intl.DateTimeFormat();
console.log(formatter.format(date)); // '3/15/2024' (US)

// Specific locale
const germanFormatter = new Intl.DateTimeFormat('de-DE');
console.log(germanFormatter.format(date)); // '15.3.2024'

const japaneseFormatter = new Intl.DateTimeFormat('ja-JP');
console.log(japaneseFormatter.format(date)); // '2024/3/15'

Date Styles#

const date = new Date('2024-03-15T14:30:00');

// Full date
new Intl.DateTimeFormat('en-US', { dateStyle: 'full' })
  .format(date); // 'Friday, March 15, 2024'

// Long date
new Intl.DateTimeFormat('en-US', { dateStyle: 'long' })
  .format(date); // 'March 15, 2024'

// Medium date
new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })
  .format(date); // 'Mar 15, 2024'

// Short date
new Intl.DateTimeFormat('en-US', { dateStyle: 'short' })
  .format(date); // '3/15/24'

Time Styles#

const date = new Date('2024-03-15T14:30:45');

// Full time
new Intl.DateTimeFormat('en-US', { timeStyle: 'full' })
  .format(date); // '2:30:45 PM Eastern Daylight Time'

// Long time
new Intl.DateTimeFormat('en-US', { timeStyle: 'long' })
  .format(date); // '2:30:45 PM EDT'

// Medium time
new Intl.DateTimeFormat('en-US', { timeStyle: 'medium' })
  .format(date); // '2:30:45 PM'

// Short time
new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })
  .format(date); // '2:30 PM'

Combined Styles#

const date = new Date('2024-03-15T14:30:00');

// Date and time
new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full',
  timeStyle: 'short',
}).format(date); // 'Friday, March 15, 2024 at 2:30 PM'

new Intl.DateTimeFormat('en-US', {
  dateStyle: 'medium',
  timeStyle: 'medium',
}).format(date); // 'Mar 15, 2024, 2:30:00 PM'

Custom Components#

const date = new Date('2024-03-15T14:30:00');

// Custom format
new Intl.DateTimeFormat('en-US', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
}).format(date); // 'Friday, March 15, 2024'

// Time components
new Intl.DateTimeFormat('en-US', {
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit',
  hour12: true,
}).format(date); // '02:30:00 PM'

// 24-hour format
new Intl.DateTimeFormat('en-US', {
  hour: '2-digit',
  minute: '2-digit',
  hour12: false,
}).format(date); // '14:30'

Component Options#

const date = new Date('2024-03-15T14:30:00');

// Weekday options: 'long', 'short', 'narrow'
console.log(new Intl.DateTimeFormat('en-US', { weekday: 'long' }).format(date)); // 'Friday'
console.log(new Intl.DateTimeFormat('en-US', { weekday: 'short' }).format(date)); // 'Fri'
console.log(new Intl.DateTimeFormat('en-US', { weekday: 'narrow' }).format(date)); // 'F'

// Month options: 'long', 'short', 'narrow', 'numeric', '2-digit'
console.log(new Intl.DateTimeFormat('en-US', { month: 'long' }).format(date)); // 'March'
console.log(new Intl.DateTimeFormat('en-US', { month: 'short' }).format(date)); // 'Mar'
console.log(new Intl.DateTimeFormat('en-US', { month: 'narrow' }).format(date)); // 'M'
console.log(new Intl.DateTimeFormat('en-US', { month: 'numeric' }).format(date)); // '3'
console.log(new Intl.DateTimeFormat('en-US', { month: '2-digit' }).format(date)); // '03'

// Day options: 'numeric', '2-digit'
console.log(new Intl.DateTimeFormat('en-US', { day: 'numeric' }).format(date)); // '15'
console.log(new Intl.DateTimeFormat('en-US', { day: '2-digit' }).format(date)); // '15'

// Year options: 'numeric', '2-digit'
console.log(new Intl.DateTimeFormat('en-US', { year: 'numeric' }).format(date)); // '2024'
console.log(new Intl.DateTimeFormat('en-US', { year: '2-digit' }).format(date)); // '24'

Time Zones#

const date = new Date('2024-03-15T14:30:00Z');

// Different time zones
const formatter = (tz) =>
  new Intl.DateTimeFormat('en-US', {
    timeStyle: 'long',
    timeZone: tz,
  });

console.log(formatter('America/New_York').format(date)); // '10:30:00 AM EDT'
console.log(formatter('America/Los_Angeles').format(date)); // '7:30:00 AM PDT'
console.log(formatter('Europe/London').format(date)); // '2:30:00 PM GMT'
console.log(formatter('Asia/Tokyo').format(date)); // '11:30:00 PM JST'

// Display time zone name
new Intl.DateTimeFormat('en-US', {
  timeZone: 'America/New_York',
  timeZoneName: 'short', // 'long', 'shortOffset', 'longOffset'
}).format(date); // '3/15/2024, EDT'

Format Parts#

const date = new Date('2024-03-15T14:30:00');

const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full',
  timeStyle: 'short',
});

// Get individual parts
const parts = formatter.formatToParts(date);
console.log(parts);
// [
//   { type: 'weekday', value: 'Friday' },
//   { type: 'literal', value: ', ' },
//   { type: 'month', value: 'March' },
//   { type: 'literal', value: ' ' },
//   { type: 'day', value: '15' },
//   { type: 'literal', value: ', ' },
//   { type: 'year', value: '2024' },
//   { type: 'literal', value: ' at ' },
//   { type: 'hour', value: '2' },
//   { type: 'literal', value: ':' },
//   { type: 'minute', value: '30' },
//   { type: 'literal', value: ' ' },
//   { type: 'dayPeriod', value: 'PM' }
// ]

// Custom formatting using parts
function customFormat(date) {
  const parts = formatter.formatToParts(date);
  const values = {};
  parts.forEach(({ type, value }) => {
    values[type] = value;
  });
  return `${values.month} ${values.day}, ${values.year}`;
}

Range Formatting#

const start = new Date('2024-03-15T09:00:00');
const end = new Date('2024-03-15T17:00:00');

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: '2-digit',
});

// Format range
console.log(formatter.formatRange(start, end));
// '9:00 AM – 5:00 PM'

// Different days
const multiDay = new Intl.DateTimeFormat('en-US', {
  month: 'short',
  day: 'numeric',
});

const startDate = new Date('2024-03-15');
const endDate = new Date('2024-03-20');
console.log(multiDay.formatRange(startDate, endDate));
// 'Mar 15 – 20'

Calendar Systems#

const date = new Date('2024-03-15');

// Different calendars
const calendars = ['gregory', 'chinese', 'hebrew', 'islamic', 'japanese'];

calendars.forEach(calendar => {
  const formatted = new Intl.DateTimeFormat('en-US', {
    calendar,
    dateStyle: 'full',
  }).format(date);
  console.log(`${calendar}: ${formatted}`);
});

// Japanese with era
new Intl.DateTimeFormat('ja-JP-u-ca-japanese', {
  era: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
}).format(date); // '令和6年3月15日'

Numbering Systems#

const date = new Date('2024-03-15');

// Arabic numerals
new Intl.DateTimeFormat('ar-EG', {
  dateStyle: 'short',
}).format(date); // '١٥/٣/٢٠٢٤'

// Thai numerals
new Intl.DateTimeFormat('th-TH-u-nu-thai', {
  dateStyle: 'short',
}).format(date); // '๑๕/๓/๖๗'

Practical Utilities#

// Reusable date formatter factory
function createDateFormatter(options = {}) {
  const {
    locale = navigator.language,
    ...formatOptions
  } = options;

  const formatter = new Intl.DateTimeFormat(locale, formatOptions);

  return {
    format: (date) => formatter.format(date),
    formatRange: (start, end) => formatter.formatRange(start, end),
    formatParts: (date) => formatter.formatToParts(date),
  };
}

// Common formatters
const formatters = {
  date: createDateFormatter({ dateStyle: 'medium' }),
  time: createDateFormatter({ timeStyle: 'short' }),
  dateTime: createDateFormatter({ dateStyle: 'medium', timeStyle: 'short' }),
  relative: createDateFormatter({
    weekday: 'long',
    month: 'long',
    day: 'numeric',
  }),
};

// Usage
const now = new Date();
console.log(formatters.date.format(now));
console.log(formatters.time.format(now));

Performance Caching#

// Cache formatters for reuse
const formatterCache = new Map();

function getFormatter(locale, options) {
  const key = `${locale}-${JSON.stringify(options)}`;

  if (!formatterCache.has(key)) {
    formatterCache.set(key, new Intl.DateTimeFormat(locale, options));
  }

  return formatterCache.get(key);
}

// Usage - formatter is cached
const formatted1 = getFormatter('en-US', { dateStyle: 'long' }).format(new Date());
const formatted2 = getFormatter('en-US', { dateStyle: 'long' }).format(new Date());

Best Practices#

Locale Selection:
✓ Use user's locale when possible
✓ Fall back gracefully
✓ Test with multiple locales
✓ Consider regional variants

Formatting:
✓ Use dateStyle/timeStyle for consistency
✓ Cache formatter instances
✓ Use formatToParts for custom layouts
✓ Handle time zones explicitly

Performance:
✓ Reuse formatter instances
✓ Create formatters outside loops
✓ Cache by locale + options
✓ Use formatRange for intervals

Avoid:
✗ Creating formatters repeatedly
✗ Ignoring time zones
✗ Hardcoding date formats
✗ Assuming locale behavior

Intl.DateTimeFormat provides powerful, locale-aware date formatting. Use dateStyle and timeStyle for consistent formatting, handle time zones explicitly with the timeZone option, and cache formatter instances for performance. The formatToParts method enables custom formatting while respecting locale conventions.