# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<DateTime>`
URL: https://generaltranslation.com/en-US/docs/react/reference/components/datetime.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format a date and time for the active locale. API reference for the `<DateTime>` component.

The `<DateTime>` component displays a `Date` value as a localized date, time, or both. It supports custom formatting options and locale overrides.

*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.*

## Overview [#overview]

Pass a `Date` as children and `<DateTime>` formats it for the active locale.

```tsx
<DateTime>{new Date(1738010355000)}</DateTime>
// Output: 1/27/2025
```

All formatting is handled locally with [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).

*Note: `<DateTime>` can cause React hydration errors in server-rendered apps. See [Avoiding hydration errors](#hydration).*

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

- **Local formatting.** The date is formatted in the browser using `Intl.DateTimeFormat`. Its value is never sent to the General Translation API.
- **Locale resolution.** The active locale determines formatting unless overridden with `locales`.
- **Time zone matters.** Without an explicit `timeZone`, output depends on the runtime's zone, which can differ between server and client.

## Props [#props]

| Prop | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`children`](#children) | The date to format. | `Date` | No | — |
| [`options`](#options) | `Intl.DateTimeFormat` options. | `Intl.DateTimeFormatOptions` | Yes | `{}` |
| [`locales`](#locales) | Locale override for formatting. | `string[]` | Yes | Active locale |
| [`name`](#name) | Variable name for the entry. | `string` | Yes | — |

### `children` [#children]

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

The date or time to format, as a `Date` object.

### `options` [#options]

**Type** `Intl.DateTimeFormatOptions` · **Optional** · **Default** `{}`

The prop accepts [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options). Common options include:

| Option | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` |
| `calendar` | Calendar system, such as `gregory`, `chinese`, or `persian`. | `string` | Yes | `'gregory'` |
| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` |
| `hour12` | Whether to use a 12-hour clock. Overrides `hourCycle`. | `boolean` | Yes | Locale-dependent |
| `hourCycle` | Hour cycle used by the clock. | `'h11' \| 'h12' \| 'h23' \| 'h24'` | Yes | Locale-dependent |
| `timeZone` | IANA time zone or UTC offset. | `string` | Yes | Runtime time zone |
| `weekday` | Width of the weekday name. | `'long' \| 'short' \| 'narrow'` | Yes | — |
| `era` | Width of the era label. | `'long' \| 'short' \| 'narrow'` | Yes | — |
| `year` | Numeric or two-digit year. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set |
| `month` | Numeric or named month format. | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes | `'numeric'` when no styles or components are set |
| `day` | Numeric or two-digit day. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set |
| `dayPeriod` | Width of labels such as "in the morning" or "at night." | `'long' \| 'short' \| 'narrow'` | Yes | — |
| `hour` | Numeric or two-digit hour. | `'numeric' \| '2-digit'` | Yes | — |
| `minute` | Numeric or two-digit minute. | `'numeric' \| '2-digit'` | Yes | — |
| `second` | Numeric or two-digit second. | `'numeric' \| '2-digit'` | Yes | — |
| `fractionalSecondDigits` | Number of fractional-second digits. | `1 \| 2 \| 3` | Yes | — |
| `timeZoneName` | Width and style of the time-zone label. | `'long' \| 'short' \| 'shortOffset' \| 'longOffset' \| 'shortGeneric' \| 'longGeneric'` | Yes | — |
| `formatMatcher` | Algorithm for matching component options to a locale format. | `'basic' \| 'best fit'` | Yes | `'best fit'` |
| `dateStyle` | Preset date format. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — |
| `timeStyle` | Preset time format. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — |

- `dateStyle` and `timeStyle` can be used together, but not with component options such as `weekday`, `year`, `month`, `day`, `hour`, `minute`, or `second`.
- `hour12` overrides `hourCycle`.
- `dayPeriod` only affects 12-hour clock formats.
- Supported calendars, numbering systems, time-zone labels, and option values depend on the JavaScript runtime.

See the [`Intl.DateTimeFormat` options documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) for the latest available options and runtime behavior.

### `locales` [#locales]

**Type** `string[]` · **Optional** · **Default** Active locale

Locales to format for. When omitted, the active locale is used. See the [locales argument](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).

### `name` [#name]

**Type** `string` · **Optional**

An optional name for the date field, used for metadata.

## Examples [#examples]

*Examples import from `gt-react`; import from your framework's package instead.*

```tsx title="EventDate.tsx"
import { DateTime } from 'gt-react';

export default function EventDate({ event }) {
  return <DateTime>{event.date}</DateTime>; // [!code highlight]
}
```

```tsx title="EventDate.tsx"
import { DateTime } from 'gt-react';

export default function EventDate({ event }) {
  return <DateTime locales={['fr-FR']}>{event.date}</DateTime>; // [!code highlight]
}
```

```tsx title="EventDate.tsx"
import { T, DateTime } from 'gt-react';

export default function EventDate({ event }) {
  return (
    <T>
      The time of the event is <DateTime>{event.date}</DateTime>. // [!code highlight]
    </T>
  );
}
```

```tsx title="EventDate.tsx"
import { DateTime } from 'gt-react';

export default function EventDate({ event }) {
  return (
    <DateTime
      options={{
        dateStyle: 'full', // [!code highlight]
        timeStyle: 'long', // [!code highlight]
        timeZone: 'Australia/Sydney', // [!code highlight]
      }}
    >
      {event.date}
    </DateTime>
  );
}
```

## Avoiding hydration errors [#hydration]

Because `<DateTime>` formats dates locally, it can produce different output on the server and the client. When React compares the server-rendered HTML to the client render and they differ, you get a hydration error. This typically happens when:

- **No explicit `timeZone` is set.** The server may run in UTC while the browser uses local time, so a timestamp can render as `"1/27/2025"` on the server and `"1/28/2025"` on the client.
- **The default locale differs between environments.** A mismatched default locale produces different strings (for example, `"27/01/2025"` vs. `"1/27/2025"`).

Pin both the locale and the time zone so the server and client always produce the same string:

```tsx
<DateTime locales={['en-US']} options={{ timeZone: 'UTC' }}>
  {event.date}
</DateTime>
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.