Doggo Storybook 0.18.0

Introduction
Buttons
Data
- Accordion
- Card
- Date
- Datetime
- Fallback
- Property List
- Relative Time
- Table
- Tabs
- Tag
- Time
- Tree
Dialog
Feedback
Form
Layout
Media
Menu
Navigation

Relative Time

Renders a DateTime or Date relative to now, such as "3 minutes ago" or "yesterday", in a <time> element.

Usage

The server renders the absolute value. The browser replaces it with the relative text in the page's language, which requires calling relativeTimes() from @woylie/doggo in your app.js. Without JavaScript, the absolute value remains.

<.relative_time value={@post.inserted_at} />

The text is converted once. Set sync to keep it up to date while the page is open:

<.relative_time value={@message.sent_at} sync />

Past a threshold, the absolute value is shown instead. With localize, the absolute value is in the user's format:

<.relative_time
  value={@event.starts_at}
  threshold={Duration.new!(week: 1)}
  localize={:medium}
/>

The title contains the absolute value.

A Date is compared by calendar day, so the text reads "yesterday" or "in 2 days".

To stop the relative times inside an element from updating, for example as a user setting, set data-relative-sync="false" on that element. It overrides sync.

VoiceOver on macOS announces the element as a group named by the title, then reads the text and the title again. Without JavaScript, past the threshold and when printing, the text is the absolute value. 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.

2026-10-01 2026-10-04

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.
format	:atom	The length of the relative text: `:long` ("3 minutes ago"), `:short` Read more Read less	:long
("3 min. ago") or `:narrow` ("3m ago"). Some locales use the same text for more than one.
formatter	:any	A function that formats the absolute value on the server. Defaults to Read more Read less
`to_string/1`. The absolute value is the text without JavaScript and before the script runs. The browser also shows it past the `threshold` and when printing, unless `localize` is set, and in the `title`, unless `localize` has `:title`.
localize	:any	The format of the absolute value in the browser, past the `threshold` Read more Read less
and in the `title`. Takes the same values as for `datetime`.
now	:any	The server's current time as a `DateTime`. The browser corrects its Read more Read less
own clock by the difference when it first sees the element. Leave it unset for a page that is cached, since the time would be stale.
numeric	:atom	With `:auto`, the text can be "yesterday"; with `:always`, it is Read more Read less	:auto
"1 day ago". Under a minute, both write "now".
rest	:global	Any additional HTML attributes.
sync	:boolean	Keeps the text up to date while the page is open. Without it, the text Read more Read less	false
is converted once.
tense	:atom	With `:past`, a value slightly in the future reads "now"; with Read more Read less	:auto
`:future`, a value slightly in the past does. Useful when the clocks of the server and the browser differ.
threshold	:any	A `Duration` without months or years, or a number of seconds. Past it, Read more Read less
the absolute value is shown instead of the relative text.
timezone	:string	The time zone of the absolute value the server renders. Read more Read less

Required value *	:any	A `DateTime` or a `Date`. Read more Read less