Humanize Duration

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.

Basic usage

This package is available as humanize-duration on npm and Bower. You can also include the JavaScript file in the browser.

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>

Usage

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'

Options

You can change the settings by passing options as the second argument:

language

Language for unit display (accepts an ISO 639-1 code from one of the supported languages).

humanizeDuration(3000, { language: 'es' })  // '3 segundos'
humanizeDuration(5000, { language: 'ko' })  // '5 초'

delimiter

String to display between the previous unit and the next value.

humanizeDuration(22140000, { delimiter: ' and ' })  // '6 hours and 9 minutes'
humanizeDuration(22140000, { delimiter: '--' })     // '6 hours--9 minutes'

spacer

String to display between each value and unit.

humanizeDuration(260040000, { spacer: ' whole ' })  // '3 whole days, 14 whole minutes'
humanizeDuration(260040000, { spacer: '' })         // '3days, 14minutes'

largest

Number representing the maximum number of units to display for the duration.

humanizeDuration(1000000000000)                  // '31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds'
humanizeDuration(1000000000000, { largest: 2 })  // '31 years, 8 month'

units

Array of strings to define which units are used to display the duration (if needed). Can be one, or a combination of any, of the following: ['y', 'mo', 'w', 'd', 'h', 'm', 's', 'ms']

humanizeDuration(3600000, { units: ['h'] })       // '1 hour'
humanizeDuration(3600000, { units: ['m'] })       // '60 minutes'
humanizeDuration(3600000, { units: ['d', 'h'] })  // '1 hour'

round

Boolean value. Use true to round the smallest unit displayed (can be combined with largest and units).

humanizeDuration(1200)                   // '1.2 seconds'
humanizeDuration(1200, { round: true })  // '1 second'
humanizeDuration(1600, { round: true })  // '2 seconds'

padUnits

Number representing the final size of the digits (enlarged with 0).

humanizeDuration(0)                          // '0 seconds'
humanizeDuration(1000, { padUnits: 2 })      // '01 second'
humanizeDuration(10000, { padUnits: 2 })     // '10 seconds'
humanizeDuration(301000, { padUnits: 2 })    // '05 minutes, 01 second'
humanizeDuration(601000, { padUnits: 2 })    // '10 minutes, 01 second'

humanizeDuration(1000, { padUnits: 3 })      // '000 seconds'

decimal

String to substitute for the decimal point in a decimal fraction.

humanizeDuration(1200)                          // '1.2 seconds'
humanizeDuration(1200, { decimal: ' point ' })  // '1 point 2 seconds'

conjunction

String to include before the final unit. You can also set serialComma to false to eliminate the final comma.

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'

unitMeasures

Customize the value used to calculate each unit of time.

humanizeDuration(400)    // '0.4 seconds'
humanizeDuration(400, {  // '1 year, 1 month, 5 days'
  unitMeasures: {
    y: 365,
    mo: 30,
    w: 7,
    d: 1
  }
})

Combined example

humanizeDuration(3602000, {
  language: 'es',
  round: true,
  spacer: ' glorioso ',
  units: ['m']
}) // '60 glorioso minutos'

Humanizers

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.

Supported languages

Humanize Duration supports the following languages:

| Language | Code | |----------------------|---------| | Arabic | ar | | Bulgarian | bg | | Catalan | ca | | Chinese, simplified | zh_CN | | Chinese, traditional | zh_TW | | Croatian | hr | | Czech | cs | | Danish | da | | Dutch | nl | | English | en | | Farsi/Persian | fa | | Finnish | fi | | French | fr | | German | de | | Greek | gr | | Hungarian | hu | | Icelandic | is | | Indonesian | id | | Italian | it | | Japanese | ja | | Korean | ko | | Lao | lo | | Lithuanian | lt | | Malay | ms | | Norwegian | no | | Polish | pl | | Portuguese | pt | | Russian | ru | | Slovak | sk | | Spanish | es | | Swedish | sv | | Turkish | tr | | Ukrainian | uk | | Urdu | ur | | Vietnamese | vi |

For a list of supported languages, you can use the getSupportedLanguages function.

humanizeDuration.getSupportedLanguages()
// ['ar', 'bg', 'ca', 'cs', da', 'de', ...]

This function won't return any new languages you define; it will only return the defaults supported by the library.

Credits

Lovingly made by Evan Hahn with help from:

• Martin Prins for language support
• Filipi Siqueira for Portuguese support
• Peter Rekdal Sunde for Norwegian support
• Michał Janiec for Polish support
• Eileen Li for Chinese support
• Tommy Brunn for Swedish support
• Giovanni Pellerano for Italian support
• Rahma Sghaier for Arabic support
• Evgenios Kastanias for Greek support
• Oleksii Mylotskyi for Ukrainian support
• Patrik Simek for Czech support
• Toni Helminen for Finnish support
• Vidmantas Drasutis for Lithuanian support
• Manh Tuan for Vietnamese support
• Leonard Lee for Indonesian & Malay support
• Jesse Jackson for documentation help
• Óli Tómas Freysson for Icelandic support
• Saeed Ganji for Farsi/Persian support
• Caner Elci for Bulgarian support
• Matej Kolesár for Slovak support
• Abdul Jalil for Urdu support
• Alexis Ablain for the addition of the leadingZeros option
• Malikoun for Lao support

Licensed under the permissive Unlicense. Enjoy!

Related modules

• pretty-ms
• angularjs-humanize-duration
• millisec
• HumanizeDuration.ts, a TypeScript version of this module
• aurelia-time