Skip to main content
Since Shoelace 2.0 Code stable

Format Date

<sl-format-date> | SlFormatDate

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


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"
import SlFormatDate from '@teamshares/shoelace/dist/react/format-date';

const App = () => <SlFormatDate 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.

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 -->
/ Human-readable date
sl-format-date month="long" day="numeric" year="numeric"
/ Time
sl-format-date hour="numeric" minute="numeric"
/ Weekday
sl-format-date weekday="long"
/ Month
sl-format-date month="long"
/ Year
sl-format-date year="numeric"
/ No formatting options
import SlFormatDate from '@teamshares/shoelace/dist/react/format-date';

const App = () => (
    {/* Human-readable date */}
    <SlFormatDate month="long" day="numeric" year="numeric" />
    <br />

    {/* Time */}
    <SlFormatDate hour="numeric" minute="numeric" />
    <br />

    {/* Weekday */}
    <SlFormatDate weekday="long" />
    <br />

    {/* Month */}
    <SlFormatDate month="long" />
    <br />

    {/* Year */}
    <SlFormatDate year="numeric" />
    <br />

    {/* No formatting options */}
    <SlFormatDate />

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"
sl-format-date hour="numeric" minute="numeric" hour-format="24"
import SlFormatDate from '@teamshares/shoelace/dist/react/format-date';

const App = () => (
    <SlFormatDate hour="numeric" minute="numeric" hour-format="12" />
    <br />
    <SlFormatDate hour="numeric" minute="numeric" hour-format="24" />


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

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"
| French:
sl-format-date lang="fr"
| Russian:
sl-format-date lang="ru"
import SlFormatDate from '@teamshares/shoelace/dist/react/format-date';

const App = () => (
    English: <SlFormatDate lang="en" />
    <br />
    French: <SlFormatDate lang="fr" />
    <br />
    Russian: <SlFormatDate lang="ru" />


If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag:

<script type="module" src=""></script>

To import this component from the CDN using a JavaScript import:

import '';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/format-date/format-date.js';

To import this component as a React component:

import SlFormatDate from '@shoelace-style/shoelace/dist/react/format-date';


Name Description Reflects Type Default
date 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(). Date | string new Date()
weekday The format for displaying the weekday. 'narrow' | 'short' | 'long' -
era The format for displaying the era. 'narrow' | 'short' | 'long' -
year The format for displaying the year. 'numeric' | '2-digit' -
month The format for displaying the month. 'numeric' | '2-digit' | 'narrow' | 'short' | 'long' -
day The format for displaying the day. 'numeric' | '2-digit' -
hour The format for displaying the hour. 'numeric' | '2-digit' -
minute The format for displaying the minute. 'numeric' | '2-digit' -
second The format for displaying the second. 'numeric' | '2-digit' -
The format for displaying the time. 'short' | 'long' -
The time zone to express the time in. string -
The format for displaying the hour. 'auto' | '12' | '24' 'auto'
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.