- 1.5.0

Datetime

Formats a DateTime or NaiveDateTime as a date time 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 with to_string/1. This:

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

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:

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

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:
Attribute Type Documentation Default Value
class :any

Any additional classes to be added.

 Read more Read less
[]

Variations of the component should be expressed via modifier attributes, and it is preferable to use styles on the parent container to arrange components on the page, but if you have to, you can use this attribute to pass additional utility classes to the component.

The value can be a string or a list of strings.
formatter :any

A function that takes a DateTime or a NaiveDateTime as an argument

 Read more Read less

and returns the value formatted for display. Defaults to to_string/1.
localize :any

Formats the text in the browser, in the page's language and the user's

 Read more Read less

time zone. The server's text is shown until the script runs, and if no JavaScript is available.

  • true: the locale's default format.
  • A style, :short, :medium, :long or :full, which the locale arranges.
  • A strftime pattern, such as "%Y-%m-%d %H:%M", for a fixed format. It can only use the directives %Y %y %m %d %H %I %M %S %p %z %%. Without a formatter, the server renders the same pattern with Calendar.strftime/2.
  • A keyword list with :style, :pattern or Intl.DateTimeFormat options, such as [weekday: :short, month: :long, day: :numeric], and :zone.

:zone is the time zone the browser formats in:

  • :viewer: the user's time zone (default)
  • :server: the time zone the server rendered the value in. Use if timezone is a zone that the user chose.
  • a time zone name.

:title sets the format of the title attribute, as a style or a pattern, for example title: :full. The browser formats the title in the same language and time zone as the text. Without :title, the title value as rendered by the server using title_formatter remains visible. If you pass a pattern and no title_formatter, the server also uses the pattern for the title.

The language is the page's lang. If it names only a language, such as en, and the browser's language is the same, the browser's own locale decides the regional conventions. Browsers do not pass on a clock set in the operating system, so pass the user's stored choice as hour_cycle: :h23 or hour_cycle: :h12.

Call localizeTimes() from @woylie/doggo in your app.js before connecting the LiveSocket. Elements with this attribute have translate="no", so that translation tools do not change their text.
precision :atom

Precision to truncate the given value with. The truncation is applied on

 Read more Read less

both the display value and the value of the datetime attribute.
rest :global

Any additional HTML attributes.
timezone :string

If set and the given value is a DateTime, the value will be shifted to

 Read more Read less

that time zone. This affects both the display value and the datetime attribute. A NaiveDateTime is not shifted.

Note that you need to configure a time zone database for this to work.

An unknown time zone raises an error. Validate a time zone taken from user input or the browser before you pass it to this component.
title_formatter :any

When provided, this function is used to format the date time value for

 Read more Read less

the title attribute. If the attribute is not set, no title attribute will be added.
Required value * :any

Either a DateTime or NaiveDateTime.

 Read more Read less