Origami Frontend Components & Services

Readme: o-date

o-date provides javascript utilities for formatting and updating dates in FT style. This component is mainly useful when you want your dates formatted to express relative time.


To provide the best non-JS fallback you should markup your dates as follows:

<time data-o-component="o-date" class="o-date" datetime="{{iso8601String}}">{FT formatted date (including time if appropriate)}</time>


To display dates in the standard relative time format, a o.DOMContentLoaded event can be dispatched on the document to auto-construct each element with a data-o-component="o-date" attribute:

document.addEventListener('DOMContentLoaded', function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));

You can also import o-date as a component.

import ODate from 'o-date'

You can run ODate.init() once the DOM has loaded if you don't want to initialise other components at the same time.

Run ODate.init(el) on any elements containing dates that are added to the page after DOM load, and if you keep a reference to the returned object you can clean them up with oDateItem.destroy() to stop processing.

o-date#format(date, tpl)

Returns a date formatted as a string


Returns the relative time since the given date, formatted as a human readable string e.g. 13 minutes ago.


Returns relative time or timestamp for a given date, in accordance with FT date formatting conventions.


Returns 'yesterday', 'today' or '' for a given date. You can request this formatting for o-date components by adding data-o-date-format="today-or-yesterday-or-nothing".


Within a given container element, converts dates to ftTime (see above) and periodically updates their values. Within the container all <time> elements with o-date in data-o-component will be updated. If a given <time> element contains an element with the class o-date__printer the relative time will be output here, otherwise it will replace the contents of the entire <time> element. Once the <time> element has been formatted by o-date, the attribute data-o-date-js is added, enabling conditional styling and/or hiding the date until it is correctly formatted.

If the el is a valid <time> element, the resulting o-date instance will be returned; otherwise, an array of created instances will be returned.


Call on any instances to stop processing date updates and release the item reference.


See the npm package @financial-times/ft-date-format for server-side date formatting. Note: It's not recommended to output the 'time ago' server side as it will not be cacheable and will not update in the browser if the user leaves the page open for a prolonged period of time.


State Major Version Last Minor Release Migration guide
✨ active 4 N/A migrate to v4
⚠ maintained 3 3.1 migrate to v3
╳ deprecated 2 2.9 -
╳ deprecated 1 1.2 -


If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.


This software is published by the Financial Times under the MIT licence.

Support Status
Switch component view

GitHub Repository

Install o-date

If using the Build Service, add o-date@^4.0.7 to your script tag.

If running a Manual Build, run bower install --save "o-date@^4.0.7".

Help & Support

o-date is maintained directly by the Origami team. If you have any questions about o-date or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com