Enhanced MS provides extensive formatting options to customize how durations are displayed. This guide covers advanced techniques for formatting milliseconds.
Using abbreviations
Abbreviations make duration strings more compact. Use the useAbbreviations option to enable this:
import ms from 'enhanced-ms';
ms(90061, { useAbbreviations: true });
// "1m 30s"
ms(90061000, { useAbbreviations: true });
// "1d 1h 1m 1s"
Limiting units
Control how many time units appear in the output using unitLimit. This is useful when you want to show a simplified duration:
ms(90061, { unitLimit: 1 });
// "1 minute"
ms(90061000, { unitLimit: 2 });
// "1 day 1 hour"
ms(90061000, { unitLimit: 3 });
// "1 day 1 hour 1 minute"
Combine unitLimit with useAbbreviations for compact, readable output: ms(90061000, { unitLimit: 2, useAbbreviations: true }) returns "1d 1h"
Customizing unit separators
Change the separator between units with the unitSeparator option:
Comma separator
Custom separator
No separator
ms(90061, { unitSeparator: ', ' });
// "1 minute, 30 seconds"
ms(90061000, { unitSeparator: ', ' });
// "1 day, 1 hour, 1 minute, 1 second"
ms(90061, { unitSeparator: ' and ' });
// "1 minute and 30 seconds"
ms(3661000, { unitSeparator: ' + ' });
// "1 hour + 1 minute + 1 second"
ms(90061, {
useAbbreviations: true,
unitSeparator: ''
});
// "1m30s"
Controlling included units
Specify exactly which time units should be included in the output:
// Only show hours and minutes
ms(90061000, {
includedUnits: ['hour', 'minute']
});
// "25 hours 1 minute"
// Only show days and hours
ms(90061000, {
includedUnits: ['day', 'hour']
});
// "1 day 1 hour"
// Show everything including milliseconds
ms(90061, {
includedUnits: ['hour', 'minute', 'second', 'millisecond']
});
// "1 minute 30 seconds 61 milliseconds"
The default includedUnits are ['year', 'day', 'hour', 'minute', 'second']. Milliseconds and sub-millisecond units are excluded by default.
Including zero values
By default, units with a value of zero are omitted. Use includeZero to show them:
ms(3661000);
// "1 hour 1 minute 1 second"
ms(3661000, {
includeZero: true,
includedUnits: ['day', 'hour', 'minute', 'second']
});
// "0 days 1 hour 1 minute 1 second"
Sub-millisecond precision
For high-precision timing, you can include microseconds and nanoseconds:
ms(1.234567, { includeSubMs: true });
// "1 millisecond 234 microseconds 567 nanoseconds"
ms(0.000123, { includeSubMs: true });
// "123 nanoseconds"
Enabling includeSubMs automatically enables includeMs as well. You can’t show sub-millisecond units without showing milliseconds.
Hiding unit names
Display only the numeric values without unit names:
ms(90061, {
hideUnitNames: true,
includedUnits: ['hour', 'minute', 'second']
});
// "0 1 30"
ms(3661000, {
hideUnitNames: true,
includedUnits: ['hour', 'minute', 'second']
});
// "1 1 1"
Padding with zeros
Use minimumDigits to pad numbers with leading zeros:
ms(90061, {
minimumDigits: 2,
includedUnits: ['hour', 'minute', 'second'],
includeZero: true
});
// "00 hours 01 minute 30 seconds"
ms(3661000, {
minimumDigits: 2,
includedUnits: ['hour', 'minute', 'second']
});
// "01 hour 01 minute 01 second"
Short preset
The short preset combines abbreviations with a 2-unit limit:
ms(90061, 'short');
// "1m 30s"
ms(90061000, 'short');
// "1d 1h"
ms(90061, { useAbbreviations: true, unitLimit: 2 });
Full precision preset
The fullPrecision preset includes all units down to nanoseconds:
ms(10.100100100, 'fullPrecision');
// "10 milliseconds 100 microseconds 100 nanoseconds"
ms(10.100100100, { includeMs: true, includeSubMs: true });
Colon notation preset
The colonNotation preset formats durations like digital clocks (HH:MM:SS):
ms(90061, 'colonNotation');
// "01:30"
ms(3661000, 'colonNotation');
// "01:01:01"
ms(90061000, 'colonNotation');
// "25:01:01"
ms(90061, {
hideUnitNames: true,
unitLimit: 3,
includeZero: true,
includedUnits: ['hour', 'minute', 'second'],
unitSeparator: ':',
minimumDigits: 2
});
Extending presets
You can extend presets with additional options:
// Start with short preset, but show 3 units
ms(90061000, {
extends: 'short',
unitLimit: 3
});
// "1d 1h 1m"
// Start with colonNotation, but use a different separator
ms(90061, {
extends: 'colonNotation',
unitSeparator: '.'
});
// "01.30"
Combining options
You can combine multiple options for precise control:
ms(90061000, {
useAbbreviations: true,
unitLimit: 3,
unitSeparator: ', ',
includeMs: true
});
// "1d, 1h, 1m"
ms(5432100, {
includedUnits: ['hour', 'minute', 'second', 'millisecond'],
includeMs: true,
minimumDigits: 2,
unitSeparator: ':'
});
// "01 hour:30 minutes:32 seconds:100 milliseconds"
Experiment with different option combinations to find the format that best suits your application’s needs.