# generaltranslation: General Translation Core SDK: formatDateTime
URL: https://generaltranslation.com/en-US/docs/core/class/methods/formatting/format-date-time.mdx
---
title: formatDateTime
description: 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.

```typescript
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

```typescript copy
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

```typescript copy
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

```typescript copy
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.DateTimeFormat` for optimal performance and accuracy
* Time zones are handled correctly when specified

## Related methods

* Check out [`Intl.DateTimeFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) for more options
* See [`formatMessage`](/docs/core/class/methods/formatting/format-message) for message formatting with date interpolation
* See standalone [`formatDateTime`](/docs/core/functions/formatting/format-date-time) for use without GT instance
* See [`getLocaleProperties`](/docs/core/class/methods/locales/get-locale-properties) for locale-specific calendar information

## Next steps