IntlDateTimeFormat

Intl.DateTimeFormat is a constructor in the ECMAScript Internationalization API (ECMA-402) that formats dates and times according to a user’s locale and display preferences. It creates formatter objects that, when given a Date, produce localized strings suitable for user interfaces and reports.

Usage and basic behavior: You create a formatter with new Intl.DateTimeFormat(locales, options). The locales parameter can be a string or an array of strings specifying the preferred locales; options customizes formatting. If locale or time zone are not specified, the runtime’s defaults are used. The resulting formatter exposes methods such as format(date) to produce a localized string, formatToParts(date) to return a structured breakdown of date and time parts, and resolvedOptions() to reveal the actual locale, calendar, numbering system, and other settings that were applied.

Options and formatting granularity: The options object can include a range of properties to control output. Common options include timeZone and timeZoneName, clock-related flags such as hour12 and hourCycle, and formatting controls for the date and time parts via year, month, day, weekday, era, hour, minute, and second. Higher-level styling can be requested with dateStyle and timeStyle (values like 'full', 'long', 'medium', 'short'), and calendar or numberingSystem can be specified for heavier localization needs. Additional flags include localeMatcher and formatMatcher to influence locale resolution and result formatting.

Examples and usage notes: A typical usage formats a date as locale-aware text, for example formatting a date with specific year, month, and day options. formatToParts is useful when building custom UIs that require precise control over each displayed element. Compatibility is broad across modern browsers and Node.js; polyfills exist for environments lacking native support.

See also: ECMAScript Internationalization API, Intl.DateTimeFormat.prototype.format, Intl.DateTimeFormat.prototype.formatToParts.