<DateTime>

Overview

The <DateTime> component renders a formatted date or time string, supporting customization such as formatting options and locale. The date or time is formatted according to the current locale and any optional parameters passed.

<DateTime>{1738010355}</DateTime>
// Output: 1/27/2025

All formatting is handled locally using the Intl.DateTimeFormat library.

Reference

Props

Prop	Type	Default
`children?`	`any`	`undefined`
`name?`	`string`	`undefined`
`value?`	`string \| number \| Date`	`undefined`
`options?`	`Intl.DateTimeFormatOptions`	`{}`
`locales?`	`string[]`	`undefined`

Description

Prop Name	Description
`children`	The content to render inside the component. Typically a date or time value. If provided, it takes precedence over the `value` prop.
`name`	Optional identifing parameter used for dictionary design patterns.
`value`	The default value for the date or time. Can be a string, number (timestamp), or Date object.
`options`	Optional formatting options for the date or time, following the `Intl.DateTimeFormatOptions` specification. Use this to define styles such as weekday names, time zones, and more.
`locales`	Optional locales to specify the formatting locale. If not provided, the user's locale is used. Read more about specifying locales here.

Returns

JSX.Element containing the formatted date or time as a string.

Examples

Basic usage

The <DateTime> component can be used to display localized date or time values.

EventDate.jsx

import { DateTime } from 'gt-react';
 
export default function EventDate(event) {
    return (
        <DateTime> {event.date} </DateTime>. 
    );
}

Specifying locales

The <DateTime> component can be used to display date or time values in a specific locale.

EventDate.jsx

 
import { DateTime } from 'gt-react';
 
export default function EventDate(event) {
    return (
        <DateTime locales={['fr-FR']}> {event.date} </DateTime>. 
    );
}

Translating `<DateTime>`

Say that you want the datetime to be displayed in a sentence that is also being translated. You can wrap the <DateTime> component in a <T> component.

EventDate.jsx

import { T, DateTime } from 'gt-react';
 
export default function EventDate(event) {
    return (
        <T id="eventDate">
            The time of the event is <DateTime> {event.date} </DateTime>.
        </T>
    );
}

Custom formatting

The <DateTime> component supports custom formatting options.

EventDate.jsx

import { DateTime } from 'gt-react';
 
export default function EventDate(event) {
    return (
        <DateTime options={{
            dateStyle: 'full', 
            timeStyle: 'long', 
            timeZone: 'Australia/Sydney', 
        }}>
            {event.date}
        </DateTime>.
    );
}

Dictionary examples

<DateTime> components can be used with dictionaries as well.

Basic usage

dictionary.jsx

import { Currency } from 'gt-react';
 
const dictionary = {
    "eventTime": <>
        The event is at <DateTime>{1738010355}</DateTime>.
    </>,
};
export default dictionary;

EventTime.jsx

import { useGT } from 'gt-react';
 
export default function EventTime() {
    const t = useGT();
    return <> t('eventTime') </>; 
}

Passing values to dictionary entries

If you want to pass values to the dictionary entry, you must specify a name for the <DateTime> component and reference it when calling the t() function.

dictionary.jsx

import { DateTime } from 'gt-react';
const dictionary = {
    "eventTime": <>The event is at <DateTime name='time'/>.</>, 
};
export default dictionary;

EventTime.jsx

import { useGT } from 'gt-react';
 
export default function EventTime() {
    const t = useGT();
    return <> t('eventTime', { time: 1738010355 }) </>; 
}

Notes

The <DateTime> component is a variable component that can be used to format date and time values.
The component uses the Intl.DateTimeFormat library for formatting.

Next Steps

For more details and usage examples of the <DateTime> component and other variable components like <Currency>, <Num>, and <Var>, see the Using Variable Components documentation.

<DateTime>

On this page