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 with to_string/1. This:

<.datetime value={~U[2023-02-05 12:22:06.003Z]} />

Will be rendered as:

  2023-02-05 12:22:06.003Z

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:

<.datetime
  value={~U[2023-02-05 14:22:06.003Z]}
  formatter={&MyApp.Cldr.DateTime.to_string!/1}
/>

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

  Feb 2, 2023, 14:22:06 PM

The component can also truncate the value before passing it to the formatter.

<.datetime
  value={~U[2023-02-05 12:22:06.003Z]}
  precision={:minute}
/>

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.

<.datetime
  value={@datetime}
  formatter={&relative_date/1}
  title_formatter={&MyApp.Cldr.DateTime.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. A long format takes more space, for example in a table column.

Finally, the component can shift a DateTime to a different time zone:

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

Which would be rendered as:

  2023-02-06 08:22:05+09:00 JST Asia/Tokyo