Doggo Storybook 0.18.4-11-g938b001

Datetime

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

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

1675599726 2023-02-05 12:22:06.003Z

Attribute	Type	Documentation	Default
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