Date

Formats a Date, DateTime, or NaiveDateTime as a date and renders it in a <time> element.

Read more Read less

Maturity: Refining

The API of this component can be considered fairly stable. As measured in October 2026, Orca reads ISO 8601 text such as 2023-02-05 as separate numbers and dashes and 08:23 as separate numbers and colons. VoiceOver reads ISO 8601 dates, but not dates with slashes such as 2/5/23. NVDA, JAWS and TalkBack have not been tested.

Usage

By default, the given value is formatted for display in the ISO 8601 format. This:

<.date value={~D[2023-02-05]} />

Will be rendered as:


You can also pass a custom formatter function. For example, if you are using ex_cldr_dates_times in your application, you could do this:

<.date
  value={~D[2023-02-05]}
  formatter={&MyApp.Cldr.Date.to_string!/1}
/>

Which, depending on your locale, may be rendered as:


Set precision to show fewer units of the date, for example only the year of a birthdate. The option is applied to the datetime attribute and the default formatter. The formatter and title_formatter functions receive the full date.

<.date value={~D[1980-05-17]} precision={:year} />

Which would be rendered as:


If you pass a title_formatter, a title attribute is added to the element. This can be useful if you want to render the value in a shortened or relative format, but still give the user access to the complete value. Touch devices do not show the title.

<.date
  value={@date}
  formatter={&relative_date/1}
  title_formatter={&MyApp.Cldr.Date.to_string!/1}
/>

VoiceOver and Orca do not announce the datetime attribute. VoiceOver on iOS and Orca do not announce the title either. VoiceOver on macOS announces an element with a title as a group named by the title, then reads the text and the title again. Make sure that the text is understandable on its own.

Orca reads the default ISO 8601 text as separate numbers and dashes. VoiceOver reads it as a date, but not a date with slashes such as 2/5/23, which localize={:short} writes in some locales. To write the month as a word, set localize to :long, or pass a formatter that uses the locale data of your application. Only a formatter changes the text for users without JavaScript.

Finally, the component can shift a DateTime to a different time zone before converting it to a date. The datetime attribute contains the full value, unless precision is set:

<.date
  value={~U[2023-02-05 23:22:05Z]}
  timezone="Asia/Tokyo"
/>

Which would be rendered as:


For DateTime and NaiveDateTime values, only the date is rendered, but the datetime attribute contains the full value.

<.date value={~D[2023-02-05]} />
<.date value={~U[2023-02-05 12:08:30Z]} />
<.date value={~N[2023-02-05 12:08:30]} />

The formatters receive the full date. Hover over the second date to see the title.

<.date value={~D[2023-02-05]} formatter={&Date.to_gregorian_days/1} />
<.date value={~D[2023-02-05]} title_formatter={&Date.to_gregorian_days/1} />

precision limits both the default display text and the datetime attribute.

<.date value={~D[1980-05-17]} precision={:year} />
<.date value={~D[1980-05-17]} precision={:month} />
<.date value={~D[1980-05-17]} precision={:month_day} />
<.date value={~D[1980-05-17]} precision={:day} />
<.date value={~U[2023-02-05 23:22:05Z]} timezone="Asia/Tokyo" />
<.date value={~D[2023-02-05]} localize />
<.date value={~D[2023-02-05]} localize={:short} />
<.date value={~D[2023-02-05]} localize={:medium} />
<.date value={~D[2023-02-05]} localize={:long} />
<.date value={~D[2023-02-05]} localize={:full} />

Pass options to choose the parts, pass a pattern to enforce a fixed format.

<.date value={~D[2023-02-05]} localize={[weekday: :long, day: :numeric, month: :long]} />
<.date value={~D[2023-02-05]} localize="%Y-%m-%d" />
<.date value={~D[2023-02-05]} localize={[style: :short, title: :full]} />
<.date value={~D[2023-02-05]} localize={[style: :short, title: "%Y-%m-%d"]} />