humanize-duration
Advanced tools
I have the time in milliseconds and I want it to become "30 minutes" or "3 days, 1 hour". Enter Humanize Duration!
This library is actively maintained but no new features will be added.
This package is available as humanize-duration on npm and Bower. You can also include the JavaScript file in the browser.
npm install humanize-duration
With require (like in Node or with common build systems):
const humanizeDuration = require("humanize-duration");
humanizeDuration(12000);
// => "12 seconds"
With a <script> tag:
<script src="humanize-duration.js"></script>
<script>
humanizeDuration(12000);
</script>
By default, Humanize Duration will humanize down to the second, and will return a decimal for the smallest unit. It will humanize in English by default.
humanizeDuration(3000);
// => "3 seconds"
humanizeDuration(2250);
// => "2.25 seconds"
humanizeDuration(97320000);
// => "1 day, 3 hours, 2 minutes"
You can change the settings by passing options as the second argument.
Language for unit display. Accepts an ISO 639-1 code from one of the supported languages.
Default: "en".
humanizeDuration(3000, { language: "es" });
// => "3 segundos"
humanizeDuration(5000, { language: "ko" });
// => "5 초"
Array of fallback languages, if the provided language cannot be found. Like language, accepts an ISO 639-1 code from one of the supported languages. It works from left to right, choosing the first language that's found.
Default: [].
humanizeDuration(3000, {
language: "bad language",
fallbacks: ["en"],
});
// => "3 seconds"
humanizeDuration(3000, {
language: "bad language",
fallbacks: ["another bad language", "es"],
});
// => "3 segundos"
Array of possible units to use. Units are y, mo, w, d, h, m, s, and ms.
Units are skipped if their count is zero. For example, if you pass a duration of 1000 and units ["h", "m", "s"], the output will be "1 second".
Must be in descending order of unit size. For example, ["h", "m"] is valid but ["m", "h"] is not.
Default: ["y", "mo", "w", "d", "h", "m", "s"]
humanizeDuration(69000, { units: ["h", "m", "s", "ms"] });
// => "1 minute, 9 seconds"
humanizeDuration(3600000, { units: ["h"] });
// => "1 hour"
humanizeDuration(3600000, { units: ["m"] });
// => "60 minutes"
humanizeDuration(3600000, { units: ["d", "h"] });
// => "1 hour"
Integer representing the maximum number of units to use.
Default: Infinity
humanizeDuration(1000000000000);
// => "31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds"
humanizeDuration(1000000000000, { largest: 2 });
// => "31 years, 8 months"
A boolean that, if true, rounds the smallest unit.
Default: false
humanizeDuration(1200);
// => "1.2 seconds"
humanizeDuration(1200, { round: true });
// => "1 second"
humanizeDuration(1600, { round: true });
// => "2 seconds"
String to display between units.
Default: ", " in most languages, " ﻭ " for Arabic
humanizeDuration(22140000);
// => "6 hours, 9 minutes"
humanizeDuration(22140000, { delimiter: " and " });
// => "6 hours and 9 minutes"
String to display between the count and the word.
Default: " "
humanizeDuration(260040000);
// => "3 days, 14 minutes"
humanizeDuration(260040000, { spacer: " whole " });
// => "3 whole days, 14 whole minutes"
String to display between the integer and decimal parts of a count, if relevant.
Default depends on the language.
humanizeDuration(1200);
// => "1.2 seconds"
humanizeDuration(1200, { decimal: " point " });
// => "1 point 2 seconds"
String to include before the final unit.
You can also set serialComma to false to eliminate the final comma.
Default: ""
humanizeDuration(22140000, { conjunction: " and " });
// => "6 hours and 9 minutes"
humanizeDuration(22141000, { conjunction: " and " });
// => "6 hours, 9 minutes, and 1 second"
humanizeDuration(22140000, { conjunction: " and ", serialComma: false });
// => "6 hours and 9 minutes"
humanizeDuration(22141000, { conjunction: " and ", serialComma: false });
// => "6 hours, 9 minutes and 1 second"
Integer that defines the maximum number of decimal points to show, if relevant. If undefined, the count will be converted to a string using Number.prototype.toString().
This does not round any numbers. See the round option.
Default: undefined
humanizeDuration(8123.456789);
// => "8.123456789 seconds"
humanizeDuration(8123.456789, { maxDecimalPoints: 3 });
// => "8.123 seconds"
humanizeDuration(8100, { maxDecimalPoints: 99 });
// => "8.1 seconds"
humanizeDuration(8000, { maxDecimalPoints: 99 });
// => "8 seconds"
humanizeDuration(7999, { maxDecimalPoints: 2 });
// => "7.99 seconds"
Array of ten strings to which will replace the numerals 0-9. Useful if a language uses different numerals.
Default: undefined for most languages, ["۰", "١", "٢", "٣", "٤", "٥", "٦", "٧", "٨", "٩"] for Arabic
humanizeDuration(1234);
// => "1.234 seconds"
humanizeDuration(1234, {
digitReplacements: [
"Zero",
"One",
"Two",
"Three",
"Four",
"Five",
"Six",
"Seven",
"Eight",
"Nine",
],
});
// => "One.TwoThreeFour seconds"
Use this option with care. It is an advanced feature.
Object used to customize the value used to calculate each unit of time. Most useful when you want to update the length of years or months, which have ambiguous lengths.
Default: { y: 31557600000, mo: 2629800000, w: 604800000, d: 86400000, h: 3600000, m: 60000, s: 1000, ms: 1 }
humanizeDuration(2629800000);
// => "1 month"
humanizeDuration(2629800000, {
unitMeasures: {
y: 31557600000,
mo: 30 * 86400000,
w: 604800000,
d: 86400000,
h: 3600000,
m: 60000,
s: 1000,
ms: 1,
},
});
// => "1 month, 10 hours, 30 minutes"
If you find yourself setting same options over and over again, you can create a humanizer that changes the defaults, which you can still override later.
const spanishHumanizer = humanizeDuration.humanizer({
language: "es",
units: ["y", "mo", "d"],
});
spanishHumanizer(71177400000);
// => "2 años, 3 meses, 2 días"
spanishHumanizer(71177400000, { units: ["d", "h"] });
// => "823 días, 19.5 horas"
You can also add new languages to humanizers. For example:
const shortEnglishHumanizer = humanizeDuration.humanizer({
language: "shortEn",
languages: {
shortEn: {
y: () => "y",
mo: () => "mo",
w: () => "w",
d: () => "d",
h: () => "h",
m: () => "m",
s: () => "s",
ms: () => "ms",
},
},
});
shortEnglishHumanizer(15600000);
// => "4 h, 20 m"
You can also add languages after initializing:
const humanizer = humanizeDuration.humanizer();
humanizer.languages.shortEn = {
y: () => "y",
// ...
Internally, the main humanizeDuration function is just a wrapper around a humanizer.
Humanize Duration supports the following languages:
| Language | Code |
|---|---|
| Afrikaans | af |
| Albanian | sq |
| Amharic | am |
| Arabic | ar |
| Basque | eu |
| Bengali | bn |
| Bulgarian | bg |
| Catalan | ca |
| Central Kurdish | ckb |
| Chinese, simplified | zh_CN |
| Chinese, traditional | zh_TW |
| Croatian | hr |
| Czech | cs |
| Danish | da |
| Dutch | nl |
| English | en |
| Esperanto | eo |
| Estonian | et |
| Faroese | fo |
| Farsi/Persian | fa |
| Finnish | fi |
| French | fr |
| German | de |
| Greek | el |
| Hebrew | he |
| Hindi | hi |
| Hungarian | hu |
| Icelandic | is |
| Indonesian | id |
| Italian | it |
| Japanese | ja |
| Kannada | kn |
| Khmer | km |
| Korean | ko |
| Kurdish | ku |
| Lao | lo |
| Latvian | lv |
| Lithuanian | lt |
| Macedonian | mk |
| Mongolian | mn |
| Malay | ms |
| Marathi | mr |
| Norwegian | no |
| Polish | pl |
| Portuguese | pt |
| Romanian | ro |
| Russian | ru |
| Serbian (Cyrillic) | sr |
| Serbian (Latin) | sr_Latn |
| Slovak | sk |
| Slovenian | sl |
| Spanish | es |
| Swahili | sw |
| Swedish | sv |
| Tamil | ta |
| Telugu | te |
| Thai | th |
| Turkish | tr |
| Ukrainian | uk |
| Urdu | ur |
| Uzbek | uz |
| Uzbek (Cyrillic) | uz_CYR |
| Vietnamese | vi |
| Welsh | cy |
For a list of supported languages, you can use the getSupportedLanguages function. The results may not be in the same order every time.
humanizeDuration.getSupportedLanguages();
// => ["af", "ar", "bg", "bn", "ca", ...]
This function won't return any new languages you define; it will only return the defaults supported by the library.
Lovingly made by Evan Hahn with help from:
Licensed under the permissive Unlicense. Enjoy!
timeAdverb, an abbreviated format, and moretimeAdverb option1d 2h 3m 4sMoment.js is a comprehensive library for parsing, validating, manipulating, and formatting dates and times in JavaScript. It includes functionality for humanizing durations, but it is more heavyweight compared to humanize-duration.
date-fns is a modern JavaScript date utility library that provides a variety of functions for working with dates, including humanizing durations. It is modular and tree-shakeable, making it a lighter alternative to Moment.js.
Luxon is a modern JavaScript library for working with dates and times, created by one of the Moment.js developers. It offers a more modern API and includes features for humanizing durations, similar to humanize-duration.
FAQs
Convert millisecond durations to English and many other languages.
The npm package humanize-duration receives a total of 1,775,808 weekly downloads. As such, humanize-duration popularity was classified as popular.
We found that humanize-duration demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket researchers discovered nine malicious NuGet packages that use time-delayed payloads to crash applications and corrupt industrial control systems.
Security News
Socket CTO Ahmad Nassri discusses why supply chain attacks now target developer machines and what AI means for the future of enterprise security.
Security News
Learn the essential steps every developer should take to stay secure on npm and reduce exposure to supply chain attacks.