Skip to main content
You can customize how Enhanced MS formats milliseconds into duration strings using various formatting options. This guide covers all available options, their types, and default values.

​
Overview

Formatting options can be passed as the second parameter to the ms() function: 
import ms from 'enhanced-ms';

ms(90000, { useAbbreviations: true, unitLimit: 2 });
// Output: "1m 30s"

​
Available options

​
extends

​
extends
FormatOptionsPreset
Extends a preset with additional options. This allows you to start with a preset and override specific settings.
ms(90000, { 
  extends: 'short',
  unitLimit: 3 
});
// Uses 'short' preset but with 3 units instead of 2
See the presets guide for available presets.

​
hideUnitNames

​
hideUnitNames
boolean
default:"false"
Hide unit names from the output. Used as part of the colonNotation preset.
ms(90000, { hideUnitNames: true });
// Output: "1 30"

ms(90000, { hideUnitNames: false });
// Output: "1 minute 30 seconds"

​
useAbbreviations

​
useAbbreviations
boolean
default:"false"
Use abbreviations for unit names instead of full names.
ms(90000, { useAbbreviations: true });
// Output: "1m 30s"

ms(90000, { useAbbreviations: false });
// Output: "1 minute 30 seconds"

​
includeZero

​
includeZero
boolean
default:"false"
Include units with the value 0 in the output. Used as part of the colonNotation preset.
ms(90000, { 
  includeZero: true,
  includedUnits: ['hour', 'minute', 'second']
});
// Output: "0 hours 1 minute 30 seconds"

ms(90000, { includeZero: false });
// Output: "1 minute 30 seconds"

​
includeMs

​
includeMs
boolean
default:"false"
Include milliseconds in the output. Shorthand for adding millisecond to the includedUnits option.
ms(1500, { includeMs: true });
// Output: "1 second 500 milliseconds"

ms(1500, { includeMs: false });
// Output: "1 second"

​
includeSubMs

​
includeSubMs
boolean
default:"false"
Include sub-millisecond units (microseconds and nanoseconds) in the output. Enabling this option automatically enables the includeMs option. Shorthand for adding microsecond and nanosecond to the includedUnits option.
ms(0.001, { includeSubMs: true });
// Output: "1 microsecond"

ms(10100.1001, { includeMs: true, includeSubMs: true });
// Output: "10 seconds 100 milliseconds 100 microseconds 100 nanoseconds"
Setting includeSubMs: true while includeMs: false will throw an error due to conflicting options.

​
includedUnits

​
includedUnits
ParseUnit[]
default:"['year', 'day', 'hour', 'minute', 'second']"
Specify which units should be included in the output. Available units: year, day, hour, minute, second, millisecond, microsecond, nanosecond.
ms(90000, { 
  includedUnits: ['hour', 'minute', 'second'] 
});
// Output: "0 hours 1 minute 30 seconds" (if includeZero is true)
// Output: "1 minute 30 seconds" (if includeZero is false)

ms(86400000, { 
  includedUnits: ['day'] 
});
// Output: "1 day"
Use includeMs and includeSubMs as convenient shortcuts instead of manually adding millisecond units to this array.

​
unitLimit

​
unitLimit
number
default:"-1"
The maximum number of units to include in the output. If the value is -1, all units will be included.
ms(3661000, { unitLimit: 2 });
// Output: "1 hour 1 minute" (seconds are omitted)

ms(3661000, { unitLimit: -1 });
// Output: "1 hour 1 minute 1 second"

ms(3661000, { unitLimit: 1 });
// Output: "1 hour"

​
unitSeparator

​
unitSeparator
string
default:"' '"
The separator to use between units.
ms(90000, { unitSeparator: ', ' });
// Output: "1 minute, 30 seconds"

ms(90000, { unitSeparator: ' and ' });
// Output: "1 minute and 30 seconds"

ms(90000, { unitSeparator: ':' });
// Output: "1 minute:30 seconds"

​
minimumDigits

​
minimumDigits
number
default:"0"
The minimum number of digits for a unit value, padding with zeroes if needed. Used as part of the colonNotation preset.
ms(90000, { 
  minimumDigits: 2,
  hideUnitNames: true 
});
// Output: "01 30"

ms(3661000, { 
  minimumDigits: 3,
  hideUnitNames: true 
});
// Output: "001 001 001"

​
Combining options

You can combine multiple options to achieve the exact formatting you need: 
ms(90000, {
  useAbbreviations: true,
  unitLimit: 2,
  unitSeparator: ', '
});
// Output: "1m, 30s"

ms(3661000, {
  includeZero: true,
  includedUnits: ['hour', 'minute', 'second'],
  minimumDigits: 2,
  hideUnitNames: true,
  unitSeparator: ':'
});
// Output: "01:01:01"

​
Using with presets

You can extend presets with custom options: 
ms(90000, {
  extends: 'short',
  unitSeparator: ', '
});
// Uses 'short' preset (abbreviations, 2 unit limit) with custom separator
// Output: "1m, 30s"

​
Type information

All formatting options are defined in the FormatOptions interface located in src/format/helpers/resolve-options.ts:5.

Build docs developers (and LLMs) love

Get started for freeTalk to us