Formatted Date Time

A lightning-formatted-date-time component shows formatted date and time. This component uses the Intl.DateTimeFormat JavaScript object to format date values. The locale set in the Salesforce user preferences determines the default formatting. This component supports these input values.

• Date object
• ISO8601 formatted string
• Timestamp

An ISO8601 formatted string matches one of the these patterns.

• YYYY
• YYYY-MM
• YYYY-MM-DD
• YYYY-MM-DDThh:mmTZD
• YYYY-MM-DDThh:mm:ssTZD
• YYYY-MM-DDThh:mm:ss.sTZD

YYYY is the year in the Gregorian calendar, MM is the month between 01 and 12, and DD is the day between 01 and 31. hh is the number of hours that have passed since midnight, mm is the number of minutes that have passed since the start of the hour, and ss is the number of seconds since the start of the minute.

TZD is the time zone designator, like Z, +hh:mm or -hh:mm. To indicate that a time is measured in Universal Time (UTC), append a Z to a time.

When no attributes other than value are specified, the component uses the default “medium” date format based on the user’s locale in Salesforce.

The locale determines the order and format of the month, day, and year. For example, the English (United States) locale’s medium date format is Oct 14, 2020 and the French (France) locale’s medium date format is 14 Oct 2020. The locale doesn’t determine the time zone. Time zone is a separate setting.

To override the medium date format, pass in the short or long format to the date-style attribute. For the previous example, the short format in English (United States) is 10/14/2020 while the long format is October 14, 2020.

The locale also determines whether to display time as 24-hour time or 12-hour time with AM and PM. You can override the locale default with the hour12 attribute. See Date and Time Display Examples for more information.

Specify optional attributes listed in the Specification tab to modify the date and time display, overriding the locale’s default formatting.

Two different attributes affect the time zone display.

The time-zone-name attribute specifies how to display the time zone. Set it to short to display a code such as EST, or long to display a description such as Eastern Standard Time.

The time-zone attribute sets a particular time zone to use to display the date and time, instead of the user device’s time zone setting. Specify a time zone from the IANA Time Zone Database, such as America/New_York, Europe/London, or Asia/Tokyo. You can’t use a time zone short code such as EST to set the time-zone attribute. You can use the code UTC however, as it’s the only short code that browsers must recognize.

When using the component to display a date only, without time, include time-zone="UTC" to ensure the correct date displays in all time zones. This requirement is especially important if you specify a timestamp for the value. Because timestamps contain time and date information, the component converts the date to the time zone in effect on the user’s device and then displays the date.

Here are some examples based on a locale of en-US.

Displays: Jan 11, 2019

1<template>
2    <lightning-formatted-date-time value="1547250828000" time-zone="UTC">
3    </lightning-formatted-date-time>
4</template>

Displays: January 11, 2019

1<template>
2    <lightning-formatted-date-time value="1547250828000" date-style="long" time-zone="UTC">
3    </lightning-formatted-date-time>
4</template>

Displays: Friday, Jan 11, 19

1<template>
2    <lightning-formatted-date-time
3        value="1547250828000"
4        year="2-digit"
5        month="short"
6        day="2-digit"
7        weekday="long"
8        time-zone="UTC"
9    >
10    </lightning-formatted-date-time>
11</template>

Displays: 1/11/2019, 3:53 PM PST (if user is in PST time zone)

1<template>
2    <lightning-formatted-date-time
3        value="1547250828000"
4        year="numeric"
5        month="numeric"
6        day="numeric"
7        hour="2-digit"
8        minute="2-digit"
9        time-zone-name="short"
10    >
11    </lightning-formatted-date-time>
12</template>

Displays: 1/11/2019, 6:53 PM EST

1<template>
2    <lightning-formatted-date-time
3        value="1547250828000"
4        year="numeric"
5        month="numeric"
6        day="numeric"
7        hour="2-digit"
8        minute="2-digit"
9        time-zone-name="short"
10        time-zone="America/New_York"
11    >
12    </lightning-formatted-date-time>
13</template>

Displays: 1/11/2019, 18:53 EST

1<template>
2    <lightning-formatted-date-time
3        value="1547250828000"
4        year="numeric"
5        month="numeric"
6        day="numeric"
7        hour="2-digit"
8        hour12={ampm}
9        minute="2-digit"
10        time-zone-name="short"
11        time-zone="America/New_York"
12    >
13    </lightning-formatted-date-time>
14</template>

Set the hour12 attribute using a variable. If set to false or any other string directly, the component interprets its value as true.

1import { LightningElement } from "lwc";
2
3export default class FormattedDateTimeHour12 extends LightningElement {
4  ampm = false;
5}

Salesforce uses the ISO8601 format YYYY-MM-DD to store date fields, which store a date without time, and includes no time zone information. When formatting dates without time, include time-zone="UTC" to ensure the correct date displays.

Salesforce uses the ISO8601 format YYYY-MM-DDThh:mm:ss.SZ for date/time fields, which stores date/time in UTC.

Assuming a user is in the en-US locale and Pacific time zone, here are two examples for a date field with the value 1965-04-09.

Displays: Apr 9, 1965

1<template>
2    <lightning-formatted-date-time value={contact.Birthdate} time-zone="UTC">
3    </lightning-formatted-date-time>
4</template>

Displays: April 09, 1965

1<template>
2    <lightning-formatted-date-time
3        value={contact.Birthdate}
4        year="numeric"
5        day="2-digit"
6        month="long"
7        time-zone="UTC"
8    >
9    </lightning-formatted-date-time>
10</template>

Assuming an en-US locale and a Pacific time zone, here’s an example for a date/time field with the value 2017-12-03T20:00:00.000+00:00.

Displays: December 03, 2017, 12:00 PM

1<template>
2    <lightning-formatted-date-time
3        value={contact.Next_Meeting__c}
4        year="numeric"
5        day="2-digit"
6        month="long"
7        hour="2-digit"
8        minute="2-digit"
9    >
10    </lightning-formatted-date-time>
11</template>

This component has usage differences from its Aura counterpart. See Base Components: Aura Vs Lightning Web Components in the Lightning Web Components Developer Guide.

The LWC Recipes GitHub repository contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses lightning-formatted-date-time, see the c-clock component.

Object Reference for the Salesforce Platform: Field Types