<DateTime>
API Reference for the <DateTime> component
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 |
---|---|---|
locales?? | string[] | undefined |
options?? | Intl.DateTimeFormatOptions | {} |
value?? | string | number | Date | undefined |
name?? | string | undefined |
children?? | any | 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. |
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.
import { DateTime } from 'gt-next';
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.
import { DateTime } from 'gt-next';
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.
import { T, DateTime } from 'gt-next';
export default function EventDate(event) {
return (
<T id="eventDate">
The time of the event is <DateTime> {event.date} </DateTime>. // [!code highlight]
</T>
);
}
Custom formatting
The <DateTime>
component supports custom formatting options.
import { DateTime } from 'gt-next';
export default function EventDate(event) {
return (
<DateTime options={{
dateStyle: 'full',
timeStyle: 'long',
timeZone: 'Australia/Sydney',
}}>
{event.date}
</DateTime>.
);
}
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.
How is this guide?