node package manager


A tiny library that formats precise time differences as a vague/fuzzy time.


A tiny JavaScript library that formats precise time differences as a vague/fuzzy time.

Displaying precise dates and times can make a website feel stuffy and formal. Using vague or fuzzy time phrases like "just now" or "3 days ago" can contribute to a friendlier interface.

vagueTime.js provides a small, clean API for converting timestamps into user-friendly phrases, heavily supported by unit tests.

3.7 kb unminified with comments, 1.2 kb minified or 693 bytes minified+gzipped.

Older versions of this library used to include translations into languages other than English. That translation process was both imperfect and a source of complexity, whereas the raison d'être of this library was to be small and simple. Localisation is a separate problem, better addressed by a dedicated solution. So, in an effort to do one thing well, the translation code was removed. It is still available in the 1.x branch and, of course, you are welcome to fork this repo if you preferred things how they were.

This library only converts in one direction: from dates/timestamps to strings. If you're interested in the opposite transformation, look elsewhere.

Via npm:

npm i vague-time

Or if you just want the git repo:

git clone

If you are running in Node.js, Browserify or another CommonJS-style environment, you can require vagueTime.js like so:

var vagueTime = require('vague-time');

It also the supports the AMD-style format preferred by Require.js.

If you are including vagueTime.js with an HTML <script> tag, or neither of the above environments are detected, the interface will be globally available as vagueTime.

vagueTime.js exports a single public function, get, which returns a vague time string based on the argument(s) that you pass it.

The arguments are passed as properties on a single options object:

  • from: Timestamp or Date instance denoting the origin point from which the vague time will be calculated. Defaults to
  • to: Timestamp or Date instance denoting the target point to which the vague time will be calculated. Defaults to
  • units: String denoting the units that the from and to timestamps are specified in. May be 's' for seconds or 'ms' for milliseconds. Defaults to 'ms'. This property has no effect when from and to are Date instances rather than timestamps.

Essentially, if to is less than from, the returned vague time will indicate some point in the past. If to is greater than from, it will indicate some point in the future.

const vagueTime = require('vague-time');
  from: 0,
  to: 60,
  units: 's'
}); // returns 'in a minute' 
  from: 1800000,
  to: 0,
  units: 'ms'
}); // returns 'half an hour ago' 
  from: new Date(2016, 10, 30),
  to: new Date(2017, 0, 31)
}); // returns 'in a couple of months' 

Install the dependencies:

npm i

Lint the code:

npm run lint

Run the tests:

npm test

Or, to run the tests in a web browser, open test/vagueTime.html.

Support for languages other than English was removed in release 2.0.0. If you were relying on that stuff, I'm sorry. You may be interested in the 1.x branch.