@internationalized/date

What is @internationalized/date?

@internationalized/date is a JavaScript library that provides utilities for handling dates and times in an internationalized manner. It offers a range of functionalities including date manipulation, formatting, and parsing, all with support for various locales and calendars.

What are @internationalized/date's main functionalities?

Date Manipulation

This feature allows you to manipulate dates by adding or subtracting days, months, or years. The code sample demonstrates how to add 5 days to a given date.

const { CalendarDate, addDays } = require('@internationalized/date');
const date = new CalendarDate(2023, 10, 5);
const newDate = addDays(date, 5);
console.log(newDate); // Outputs: CalendarDate { year: 2023, month: 10, day: 10 }

Date Formatting

This feature provides utilities to format dates according to different locales. The code sample shows how to format a date in the 'en-US' locale.

const { CalendarDate, DateFormatter } = require('@internationalized/date');
const date = new CalendarDate(2023, 10, 5);
const formatter = new DateFormatter('en-US');
console.log(formatter.format(date)); // Outputs: 10/5/2023

Date Parsing

This feature allows you to parse date strings into date objects according to different locales. The code sample demonstrates parsing a date string in the 'en-US' locale.

const { DateFormatter } = require('@internationalized/date');
const formatter = new DateFormatter('en-US');
const date = formatter.parse('10/5/2023');
console.log(date); // Outputs: CalendarDate { year: 2023, month: 10, day: 5 }

Support for Multiple Calendars

This feature provides support for multiple calendar systems. The code sample shows how to create a date object using the Japanese calendar.

const { CalendarDate, JapaneseCalendar } = require('@internationalized/date');
const date = new CalendarDate(2023, 10, 5, new JapaneseCalendar());
console.log(date); // Outputs: CalendarDate { year: 2023, month: 10, day: 5, calendar: JapaneseCalendar }

Other packages similar to @internationalized/date

moment

Moment.js is a widely-used library for parsing, validating, manipulating, and formatting dates. It offers extensive support for date manipulation and formatting but lacks built-in support for multiple calendar systems and locales compared to @internationalized/date.

date-fns

date-fns is a modern JavaScript date utility library that provides a comprehensive set of functions for date manipulation and formatting. It is modular and tree-shakeable, making it a lightweight alternative to Moment.js. However, it does not offer the same level of internationalization and calendar support as @internationalized/date.

luxon

Luxon is a modern library for working with dates and times in JavaScript. It is built on top of the native JavaScript DateTime API and provides a more comprehensive and easier-to-use interface. Luxon offers good support for internationalization but does not support multiple calendar systems like @internationalized/date.

README

@internationalized/date

The @internationalized/date package provides objects and functions for representing and manipulating dates and times in a locale-aware manner.

Features

• Typed objects – Includes immutable objects to represent dates, times, calendars, and more.
• International calendars – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more.
• Manipulation – Add and subtract durations, set and cycle fields, and more.
• Conversion – Convert between calendar systems, time zones, string representations, and object types.
• Queries – Compare dates and times for ordering or full/partial equality. Determine locale-specific metadata such as day of week, weekend/weekday, etc.
• Time zone aware – The ZonedDateTime object supports time zone aware date and time manipulation.
• Predictable – The API is designed to resolve ambiguity in all operations explicitly, including time zone conversions, arithmetic involving daylight saving time, locale-specific queries, and more.
• Small bundle size – The entire library including all calendars and functions is 8 kB minified and compressed with Brotli.
• Tree shakeable – Only include the functions and calendar systems you need. For example, if you only use the Gregorian calendar and builtin CalendarDate methods, it's just 2.8 kB.

Introduction

Dates and times are represented in many different ways by cultures around the world. This includes differences in calendar systems, time zones, daylight saving time rules, date and time formatting, weekday and weekend rules, and much more. When building applications that support users around the world, it is important to handle these aspects correctly for each locale. The @internationalized/date package provides a library of objects and functions to perform date and time related manipulation, queries, and conversions that work across locales and calendars.

By default, JavaScript represents dates and times using the Date object. However, Date has many problems, including a very difficult to use API, lack of all internationalization support, and more. The Temporal proposal will eventually address this in the language, and @internationalized/date is heavily inspired by it. We hope to back the objects in this package with it once it is implemented in browsers.

Package structure

The @internationalized/date package includes the following object types:

• Calendar – An interface which provides calendar conversion and metadata like number of days in month, and number of months in year. Many implementations are provided to support the most commonly used calendar systems.
• CalendarDate – An immutable object that stores a date associated with a specific calendar system, without any time components.
• CalendarDateTime – An immutable object that represents a date and time without a time zone, in a specific calendar system.
• ZonedDateTime – An immutable object that represents a date and time in a specific time zone and calendar system.
• Time – An immutable object that stores a clock time without any date components.

Each object includes methods to allow basic manipulation and conversion functionality, such as adding and subtracting durations, and formatting as an ISO 8601 string. Additional less commonly used functions can be imported from the @internationalized/date package, and passed a date object as a parameter. This includes functions to parse ISO 8601 strings, query properties such as day of week, convert between time zones and much more. See the documentation for each of the objects to learn more about the supported methods and functions.

This example constructs a CalendarDate object, manipulates it to get the start of the next week, and converts it to a string representation.

import {CalendarDate, startOfWeek} from '@internationalized/date';

let date = new CalendarDate(2022, 2, 3);
date = date.add({weeks: 1});
date = startOfWeek(date, 'en-US');
date.toString(); // 2022-02-06