Skip to content
Directive making date elements display time relatively
Find file
Latest commit 1845c94 @ehd Merge pull request #10 from boennemann/remove-make
Remove `make` overhead
Failed to load latest commit information.
example Update build & example
.gitignore chore(git): ignore node_modules and dist
.jshintrc Disable es5 option in jshint config (default since 2.0)
.npmignore chore(make): remove Makefile
index.js fix: correctly check for provided dependencies
package.json chore(npm): update devDependencies


relative is an angular directive which parses its element's text-content or datetime attribute and replaces the contents with a time relative to now, e.g., "1 day ago" instead of a fixed date or "in 87 years" instead of "2100".

It also sets the element's title attribute to a nicely formatted time localized to the browser's timezone so people can hover to get the original datetime.

To learn about other options see below.


If you've understood programming you can also:

npm install ng-time-relative


Easy way:

<script src="ng-time-relative.js"></script>
// Add timeRelative as dependency to your module definition
var app = angular.module('YourApp', ['timeRelative']);

And add timeRelative to your module's dependencies to the relative directive.

The module is also exposed as a CommonJS module and its dependencies can be manually injected.

This library depends on the excellent Moment.js ~2.0.0 for date parsing and formatting. moment can be provided as a constant like this:

var app = angular.module('app', []);
app.constant('moment', moment);

This internally more or less does app.directive('relative', ...).

DOM output Examples

Party like it's <time relative>1999</time>
-> Party like it's 14 years ago

<time class="relative" without-suffix>April 5, 2063</time> until warp speed
-> 50 years until warp speed

The UNIX Epoch started <time relative datetime="1970-01-01"></time>
-> The UNIX Epoch started 43 years ago

Torment: Tides of Numenera was funded
<time class="relative" datetime="2013-04-06T00:00:00Z">a while ago</time>
-> Torment: Tides of Numenera was funded 2 days ago


Restrictions: (AC) The directive can be used as a class or attribute.

Input: Date is parsed from the element's text content or datetime attribute.


  • datetime="date": Use date to calculate time difference. Ignores element text-content.

  • to="then": Use then instead of now to calculate time difference. Defaults to current time.

  • without-suffix: Don't display a suffix, e.g., "15 years" instead of "15 years ago" or "in 15 years".

Performance notes

Every directive instance sets up a timeout. The timeouts are however set up in a way that they fire only when it makes sense, as in, they fire when the text rendered by Moment.js would actually change, not before and not after.

Something went wrong with that request. Please try again.