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 time part of the given value is formatted for display with to_string/1. For a DateTime or NaiveDateTime, the datetime attribute contains the full value. This:

<.time value={~T[12:22:06.003]} />

Will be rendered as:

  12:22:06.003

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:

<.time
  value={~T[12:22:06.003]}
  formatter={&MyApp.Cldr.Time.to_string!/1}
/>

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

  14:22:06 PM

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

<.time
  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.

<.time
  value={@time}
  formatter={&relative_time/1}
  title_formatter={&MyApp.Cldr.Time.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.

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

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

Which would be rendered as:

  08:22:05