Format Date

sl-format-date

Formats a date/time using the specified locale and options.

Examples

Date Formatter Basics

Localization is handled by the browser’s Intl.DateTimeFormat API. No language packs are required.

<!-- Shoelace 2 release date 🎉 -->
<sl-format-date date="2020-07-15T09:17:00-04:00"></sl-format-date>

/ Shoelace 2 release date 🎉
sl-format-date date="2020-07-15T09:17:00-04:00"

The date attribute determines the date/time to use when formatting. It must be a string that Date.parse() can interpret or a Date object set via JavaScript. If omitted, the current date/time will be assumed.

When using strings, avoid ambiguous dates such as 03/04/2020 which can be interpreted as March 4 or April 3 depending on the user’s browser and locale. Instead, always use a valid ISO 8601 date time string to ensure the date will be parsed properly by all clients.

Date & Time Formatting

Formatting options are based on those found in the Intl.DateTimeFormat API. When formatting options are provided, the date/time will be formatted according to those values. When no formatting options are provided, a localized, numeric date will be displayed instead.

<!-- Human-readable date -->
<sl-format-date month="long" day="numeric" year="numeric"></sl-format-date><br />

<!-- Time -->
<sl-format-date hour="numeric" minute="numeric"></sl-format-date><br />

<!-- Weekday -->
<sl-format-date weekday="long"></sl-format-date><br />

<!-- Month -->
<sl-format-date month="long"></sl-format-date><br />

<!-- Year -->
<sl-format-date year="numeric"></sl-format-date><br />

<!-- No formatting options -->
<sl-format-date></sl-format-date>

/ Human-readable date
sl-format-date month="long" day="numeric" year="numeric"
br
/ Time
sl-format-date hour="numeric" minute="numeric"
br
/ Weekday
sl-format-date weekday="long"
br
/ Month
sl-format-date month="long"
br
/ Year
sl-format-date year="numeric"
br
/ No formatting options
sl-format-date

Hour Formatting

By default, the browser will determine whether to use 12-hour or 24-hour time. To force one or the other, set the hour-format attribute to 12 or 24.

<sl-format-date hour="numeric" minute="numeric" hour-format="12"></sl-format-date><br />
<sl-format-date hour="numeric" minute="numeric" hour-format="24"></sl-format-date>

sl-format-date hour="numeric" minute="numeric" hour-format="12"
br
sl-format-date hour="numeric" minute="numeric" hour-format="24"

Localization

Use the lang attribute to set the date/time formatting locale.

English:
French:
Russian:

English: <sl-format-date lang="en"></sl-format-date><br />
French: <sl-format-date lang="fr"></sl-format-date><br />
Russian: <sl-format-date lang="ru"></sl-format-date>

| English:
sl-format-date lang="en"
br
| French:
sl-format-date lang="fr"
br
| Russian:
sl-format-date lang="ru"

Component Props

Property	Default	Details
`date`	`new Date()`	`Date \| string` The date/time to format. If not set, the current date and time will be used. When passing a string, it’s strongly recommended to use the ISO 8601 format to ensure timezones are handled correctly. To convert a date to this format in JavaScript, use `date.toISOString()`.
`weekday`	—	`'narrow' \| 'short' \| 'long'` The format for displaying the weekday.
`era`	—	`'narrow' \| 'short' \| 'long'` The format for displaying the era.
`year`	—	`'numeric' \| '2-digit'` The format for displaying the year.
`month`	—	`'numeric' \| '2-digit' \| 'narrow' \| 'short' \| 'long'` The format for displaying the month.
`day`	—	`'numeric' \| '2-digit'` The format for displaying the day.
`hour`	—	`'numeric' \| '2-digit'` The format for displaying the hour.
`minute`	—	`'numeric' \| '2-digit'` The format for displaying the minute.
`second`	—	`'numeric' \| '2-digit'` The format for displaying the second.
`timeZoneName` `time-zone-name`	—	`'short' \| 'long'` The format for displaying the time.
`timeZone` `time-zone`	—	`string` The time zone to express the time in.
`hourFormat` `hour-format`	`'auto'`	`'auto' \| '12' \| '24'` The format for displaying the hour.
`updateComplete`		A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.