Formatted Date Time

A lightning:formattedDateTime component displays 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 formatting. The following input values are supported.

• Date object
• ISO8601 formatted string
• Timestamp

An ISO8601 formatted string matches one of the following 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 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 date format is Oct 14, 2020 and the French (France) locale’s date format is 14 Oct 2020. The locale doesn’t determine the time zone. Time zone is a separate setting.

The locale also determines whether to display time as 24-hour time or 12-hour time with AM and PM.

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

Two different attributes affect the time zone display.

The timeZoneName 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 timeZone 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 timeZone 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, include timeZone="UTC" to ensure the correct date displays in all time zones. This 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 user’s timezone in Salesforce and then displays the date.

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

Displays: Jan 11, 2019

1<aura:component>
2  <lightning:formattedDateTime value="1547250828000" timeZone="UTC" />
3</aura:component>

Displays: Friday, Jan 11, 19

1<aura:component>
2  <lightning:formattedDateTime
3    value="1547250828000"
4    year="2-digit"
5    month="short"
6    day="2-digit"
7    weekday="long"
8    timeZone="UTC"
9  />
10</aura:component>

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

1<aura:component>
2  <lightning:formattedDateTime
3    value="1547250828000"
4    year="numeric"
5    month="numeric"
6    day="numeric"
7    hour="2-digit"
8    minute="2-digit"
9    timeZoneName="short"
10  />
11</aura:component>

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

1<aura:component>
2  <lightning:formattedDateTime
3    value="1547250828000"
4    year="numeric"
5    month="numeric"
6    day="numeric"
7    hour="2-digit"
8    minute="2-digit"
9    timeZoneName="short"
10    timeZone="America/New_York"
11  />
12</aura:component>

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

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<lightning:formattedDateTime value="{!contact.Birthdate}" timeZone="UTC" />

Displays: April 09, 1965

1<lightning:formattedDateTime
2  value="{!contact.Birthdate}"
3  year="numeric"
4  day="2-digit"
5  month="long"
6  timeZone="UTC"
7/>

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<lightning:formattedDateTime
2  value="{!contact.Next_Meeting__c}"
3  year="numeric"
4  day="2-digit"
5  month="long"
6  hour="2-digit"
7  minute="2-digit"
8/>