# General Translation Platform: formatDateTime
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/formatting/format-date-time.mdx
---

title: formatDateTime
description: Format dates and times by locale. API reference for formatDateTime.

---

Formats a date and time according to locale-specific conventions on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation uses the built-in `Intl.DateTimeFormat` API to handle date formats, time formats, calendars, and time zones automatically for the target locale.

## Overview [#overview]

Call `formatDateTime` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with a `Date` and an optional options object. It returns the formatted date and time as a string.

```typescript
const gt = new GT({ targetLocale: 'de-DE' });

const formatted = gt.formatDateTime(new Date(), {
  dateStyle: 'medium',
  timeStyle: 'short',
});
// "25.09.2025, 18:06" (German date/time formatting)
```

Signature:

```typescript
formatDateTime(
  date: Date,
  options?: { locales?: string | string[] } & Intl.DateTimeFormatOptions
): string
```

*Note: `formatDateTime` runs locally using `Intl.DateTimeFormat` and does not require an API key. It uses the instance's rendering locales by default; pass `locales` to override. For formatting without a `GT` instance, see the standalone [`formatDateTime`](/docs/platform/core/reference/utility-functions/formatting/format-date-time).*

## How it works [#how-it-works]

* **Locale resolution.** By default, the method formats for the instance's locales. Pass `locales` in the options to override them for a single call.
* **Intl-backed.** Formatting is delegated to the browser-native [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), so all standard `Intl.DateTimeFormatOptions` are supported.
* **Time zones.** Time zones are handled correctly when a `timeZone` is specified; otherwise, the runtime's local time zone is used.

## Parameters [#parameters]

| Parameter             | Description                                                                                 | Type     | Optional | Default |
| --------------------- | ------------------------------------------------------------------------------------------- | -------- | -------- | ------- |
| [`date`](#date)       | The date object to format.                                                                  | `Date`   | No       | —       |
| [`options`](#options) | Formatting configuration, extending `Intl.DateTimeFormatOptions` with a `locales` override. | `object` | Yes      | —       |

### `date` [#date]

**Type** `Date` · **Required**

The `Date` object to format.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Intl.DateTimeFormatOptions` · **Optional**

Formatting configuration. Extends `Intl.DateTimeFormatOptions` with an additional `locales` field:

| Name                     | Description                                       | Type                                                                                    | Optional | Default           |
| ------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------- | -------- | ----------------- |
| `locales`                | Override locales for formatting.                  | `string \| string[]`                                                                    | Yes      | instance locales  |
| `localeMatcher`          | Locale matching algorithm.                        | `'lookup' \| 'best fit'`                                                                | Yes      | `'best fit'`      |
| `dateStyle`              | Overall date formatting style.                    | `'full' \| 'long' \| 'medium' \| 'short'`                                               | Yes      | —                 |
| `timeStyle`              | Overall time formatting style.                    | `'full' \| 'long' \| 'medium' \| 'short'`                                               | Yes      | —                 |
| `weekday`                | Weekday representation.                           | `'long' \| 'short' \| 'narrow'`                                                         | Yes      | —                 |
| `era`                    | Era representation.                               | `'long' \| 'short' \| 'narrow'`                                                         | Yes      | —                 |
| `year`                   | Year representation.                              | `'numeric' \| '2-digit'`                                                                | Yes      | —                 |
| `month`                  | Month representation.                             | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'`                               | Yes      | —                 |
| `day`                    | Day representation.                               | `'numeric' \| '2-digit'`                                                                | Yes      | —                 |
| `dayPeriod`              | Day period formatting (morning, afternoon, etc.). | `'narrow' \| 'short' \| 'long'`                                                         | Yes      | —                 |
| `hour`                   | Hour representation.                              | `'numeric' \| '2-digit'`                                                                | Yes      | —                 |
| `minute`                 | Minute representation.                            | `'numeric' \| '2-digit'`                                                                | Yes      | —                 |
| `second`                 | Second representation.                            | `'numeric' \| '2-digit'`                                                                | Yes      | —                 |
| `fractionalSecondDigits` | Number of fractional second digits.               | `1 \| 2 \| 3`                                                                           | Yes      | —                 |
| `timeZoneName`           | Time zone name format.                            | `'long' \| 'short' \| 'longOffset' \| 'shortOffset' \| 'longGeneric' \| 'shortGeneric'` | Yes      | —                 |
| `timeZone`               | IANA time zone identifier.                        | `string`                                                                                | Yes      | runtime time zone |
| `hour12`                 | Whether to use 12-hour time format.               | `boolean`                                                                               | Yes      | —                 |
| `hourCycle`              | Hour cycle preference.                            | `'h11' \| 'h12' \| 'h23' \| 'h24'`                                                      | Yes      | —                 |
| `calendar`               | Calendar system to use.                           | `string`                                                                                | Yes      | `'gregory'`       |
| `numberingSystem`        | Numbering system for digits.                      | `string`                                                                                | Yes      | `'latn'`          |
| `formatMatcher`          | Format matching algorithm.                        | `'basic' \| 'best fit'`                                                                 | Yes      | `'best fit'`      |

## Returns [#returns]

**Type** `string`

The formatted date and time, following the target locale’s conventions.

## Examples [#examples]

*Note: examples without an explicit `timeZone` render in the runtime's local time zone; the time-of-day outputs below assume `America/Los_Angeles` (UTC−7 on this date).*

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

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

```typescript
// 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 [#notes]

* Date formatting automatically follows locale-specific conventions.
* The method uses browser-native `Intl.DateTimeFormat` for performance and accuracy.
* Time zones are handled correctly when specified.