Maturity: Refining

The API of this component can be considered fairly stable, but there are still uncertainties about accessibility aspects, such as the handling of the <time> element and its datetime attribute by screen readers and the limited accessibility of the title attribute.

Usage

By default, the given value is formatted for display with to_string/1. This:

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

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. Note that the title attribute is only accessible to users who use a pointer device. Some screen readers may however announce the datetime attribute that is always added.

<.time
  value={@time}
  formatter={&relative_time/1}
  title_formatter={&MyApp.Cldr.Time.to_string!/1}
/>

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