# General Translation React SDKs (gt-react, gt-next, gt-react-native): `` URL: https://generaltranslation.com/en-GB/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 `` component. The `` component displays a `Date` value as a localised 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 `` formats it for the active locale. ```tsx {new Date(1738010355000)} // Output: 27/01/2025 ``` All formatting is handled locally with [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). *Note: `` 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 the formatting unless overridden by `locales`. * **Time zone matters.** Without an explicit `timeZone`, output depends on the runtime's time zone, which can differ between server and client. ## Props [#props] | Prop | Description | Type | Optional | Default | | ----------------------- | ------------------------------- | ---------------------------- | -------- | ------------- | | [`children`](#children) | The date to be formatted. | `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 behaviour. ### `locales` [#locales] **Type** `string[]` · **Optional** · **Default** Active locale The 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 {event.date}; // [!code highlight] } ``` ```tsx title="EventDate.tsx" import { DateTime } from 'gt-react'; export default function EventDate({ event }) { return {event.date}; // [!code highlight] } ``` ```tsx title="EventDate.tsx" import { T, DateTime } from 'gt-react'; export default function EventDate({ event }) { return ( The time of the event is {event.date}. // [!code highlight] ); } ``` ```tsx title="EventDate.tsx" import { DateTime } from 'gt-react'; export default function EventDate({ event }) { return ( {event.date} ); } ``` ## Avoiding hydration errors [#hydration] Because `` 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 {event.date} ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.