Format Date
<ahi-format-date> | AhiFormatDate
Formats a date/time using the specified locale and options. Localization is handled by the browser’s Intl.DateTimeFormat API. No language packs are required.
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.
<!-- Azalea Kit UI initial commit date 🎉 -->
<ahi-format-date date="2022-05-13T18:28:03-04:00"></ahi-format-date>
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.
Examples
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 -->
<ahi-format-date month="long" day="numeric" year="numeric"></ahi-format-date><br />
<!-- Time -->
<ahi-format-date hour="numeric" minute="numeric"></ahi-format-date><br />
<!-- Weekday -->
<ahi-format-date weekday="long"></ahi-format-date><br />
<!-- Month -->
<ahi-format-date month="long"></ahi-format-date><br />
<!-- Year -->
<ahi-format-date year="numeric"></ahi-format-date><br />
<!-- No formatting options -->
<ahi-format-date></ahi-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.
<ahi-format-date hour="numeric" minute="numeric" hour-format="12"></ahi-format-date>
<br />
<ahi-format-date hour="numeric" minute="numeric" hour-format="24"></ahi-format-date>
Setting a Default Time Zone
By default, the date will be formatted based on the time zone of the user’s computer. If you would like to
set a specific default time zone, use the
DefaultTimeZoneController.setDefaultTimeZone function.
<script type="module">
import { DefaultTimeZoneController } from '/azalea-kit-ui/dist/utilities/default-time-zone.js';
DefaultTimeZoneController.setDefaultTimeZone('America/Costa_Rica');
</script>
Precision
By default, the date property is treated as a datetime string, which means that dates of the
format YYYY-MM-DD will be set to midnight on the given day. This can cause the wrong date to be displayed
when applying a time zone to the date. To avoid this, you can set the precision property to
"date".
In cases where it is uncertain whether the date will have a time component, you can set the
precision to "auto" to automatically determine whether the date should be treated
as a datetime or just a date.
Setting precision="date" will disregard the hour, minute,
second, timeZoneName, timeZone, and hour12 properties,
as well as the default time zone. This also applies if precision="auto" is set and the given
date is determined not to have any time component.
“date” precision:
“auto” precision:
"datetime" precision: <ahi-format-date precision="datetime" date="2023-04-05" time-zone="America/New_York"></ahi-format-date>
<br/>
"date" precision: <ahi-format-date precision="date" date="2023-04-05" time-zone="America/New_York"></ahi-format-date>
<br/>
"auto" precision: <ahi-format-date precision="auto" date="2023-04-05" time-zone="America/New_York"></ahi-format-date>
Importing
To import this component using a script tag:
<script type="module" src="/path/to/azalea-kit-ui/dist/components/format-date/format-date.js"></script>To import this component using a bundler:
import '@azaleahealth/azalea-kit-ui/dist/components/format-date/format-date.js';Properties
| Name | Description | 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()
|
|
precision
|
Whether the given datetime string should be treated as a date and time or just a date. If set to
"date" the time zone and any time formatting options to be ignored.
|
'date' | 'datetime' | 'auto'
|
'datetime'
|
|
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'
|
- | |
timeZoneName
time-zone-name
|
The format for displaying the time. |
'short' | 'long'
|
- | |
timeZone
time-zone
|
The time zone to express the time in. |
string
|
- | |
hourFormat
hour-format
|
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 properties and attributes.