formatDateTime
API Reference for the formatDateTime method to format dates and times according to locale conventions
Overview
The formatDateTime method formats dates and times according to locale-specific conventions using the Internationalization API.
It handles date formats, time formats, calendars, and time zones automatically based on the target locale.
const gt = new GT({ targetLocale: 'de-DE' });
const formatted = gt.formatDateTime(new Date(), {
dateStyle: 'medium',
timeStyle: 'short'
});
// Returns: "25.09.2025, 18:06" (German date/time formatting)Reference
Parameters
| Name | Type | Description |
|---|---|---|
date | Date | The date object to format |
options? | DateTimeFormatOptions | Optional formatting configuration |
DateTimeFormatOptions
Extends Intl.DateTimeFormatOptions with additional locale specification:
| Name | Type | Description |
|---|---|---|
locales? | string | string[] | Override locales for formatting (defaults to instance locales) |
localeMatcher? | 'lookup' | 'best fit' | Locale matching algorithm (default: 'best fit') |
dateStyle? | 'full' | 'long' | 'medium' | 'short' | Overall date formatting style |
timeStyle? | 'full' | 'long' | 'medium' | 'short' | Overall time formatting style |
weekday? | 'long' | 'short' | 'narrow' | Weekday representation |
era? | 'long' | 'short' | 'narrow' | Era representation |
year? | 'numeric' | '2-digit' | Year representation |
month? | 'numeric' | '2-digit' | 'long' | 'short' | 'narrow' | Month representation |
day? | 'numeric' | '2-digit' | Day representation |
dayPeriod? | 'narrow' | 'short' | 'long' | Day period formatting (morning, afternoon, etc.) |
hour? | 'numeric' | '2-digit' | Hour representation |
minute? | 'numeric' | '2-digit' | Minute representation |
second? | 'numeric' | '2-digit' | Second representation |
fractionalSecondDigits? | 1 | 2 | 3 | Number of fractional second digits |
timeZoneName? | 'long' | 'short' | 'longOffset' | 'shortOffset' | 'longGeneric' | 'shortGeneric' | Time zone name format |
timeZone? | string | IANA time zone identifier |
hour12? | boolean | Whether to use 12-hour time format |
hourCycle? | 'h11' | 'h12' | 'h23' | 'h24' | Hour cycle preference |
calendar? | string | Calendar system to use |
numberingSystem? | string | Numbering system for digits |
formatMatcher? | 'basic' | 'best fit' | Format matching algorithm (default: 'best fit') |
Returns
string - The formatted date and time according to locale conventions.
Examples
Basic Date and Time Formatting
import { GT } from 'generaltranslation';
const gt = new GT({ targetLocale: 'en-US' });
const date = new Date('2024-03-14T14:30:45Z');
// Basic date formatting (uses default options)
console.log(gt.formatDateTime(date));
// Output: "3/14/2024"
// German locale formatting
console.log(gt.formatDateTime(date, { locales: 'de-DE' }));
// Output: "14.3.2024"
// Japanese locale formatting
console.log(gt.formatDateTime(date, { locales: 'ja-JP' }));
// Output: "2024/3/14"Date and Time Styles
const date = new Date('2024-03-14T14:30:45Z');
// Full date style
console.log(gt.formatDateTime(date, { dateStyle: 'full' }));
// Output: "Thursday, March 14, 2024"
// Long date with short time
console.log(gt.formatDateTime(date, {
dateStyle: 'long',
timeStyle: 'short'
}));
// Output: "March 14, 2024 at 7:30 AM"
// Custom date components
console.log(gt.formatDateTime(date, {
weekday: 'long',
year: 'numeric',
month: 'long',
day: 'numeric'
}));
// Output: "Thursday, March 14, 2024"Time Zone and Hour Format
const date = new Date('2024-03-14T14:30:45Z');
// Force 12-hour format
console.log(gt.formatDateTime(date, {
hour: 'numeric',
minute: '2-digit',
hour12: true
}));
// Output: "7:30 AM"
// Force 24-hour format
console.log(gt.formatDateTime(date, {
hour: 'numeric',
minute: '2-digit',
hour12: false
}));
// Output: "07:30"
// Specific time zone
console.log(gt.formatDateTime(date, {
timeZone: 'America/New_York',
dateStyle: 'medium',
timeStyle: 'short'
}));
// Output: "Mar 14, 2024, 10:30 AM"Notes
- Date formatting follows locale-specific conventions automatically
- The method uses browser-native
Intl.DateTimeFormatfor optimal performance and accuracy - Time zones are handled correctly when specified
Related Methods
- Check out
Intl.DateTimeFormatdocumentation for more options - See
formatRelativeTimefor relative date formatting ("2 days ago") - See
formatMessagefor message formatting with date interpolation - See standalone
formatDateTimefor use without GT instance - See
getLocalePropertiesfor locale-specific calendar information
Next Steps
- See Formatting Guide for comprehensive date/time formatting strategies
- See Internationalization Guide for locale-aware date handling
How is this guide?