pretty-ms: Convert Milliseconds to Readable Time

pretty-ms is a JavaScript utility that converts millisecond durations into readable time strings, from 900ms to 15d 11h 23m 20s.

It accepts numbers and BigInts, with abbreviated units, full-word labels, and clock-style formatting for timers and elapsed-time logs.

Features

• Formats negative durations and zero values.
• Limits output to a selected number of time units.
• Controls decimal precision for seconds and milliseconds.
• Shows optional microseconds and nanoseconds.
• Displays sub-second values as decimal seconds.
• Converts years and days into total days or hours.

How To Use It

Installation

Install pretty-ms with NPM.

npm install pretty-ms

Basic Usage

Import the default function and pass a duration in milliseconds. It returns a formatted string that you can display on a page or write to a log.

import prettyMilliseconds from 'pretty-ms';
prettyMilliseconds(90500);       // '1m 30.5s'
prettyMilliseconds(900);         // '900ms'
prettyMilliseconds(1337000000n); // '15d 11h 23m 20s'

Format Timer Labels

Set colonNotation for a digital-clock readout. When you also set hideSeconds, durations of at least one minute use hours and minutes. Durations below one minute retain the seconds field.

prettyMilliseconds(95500, {colonNotation: true});
// '1:35.5'
prettyMilliseconds(60000, {colonNotation: true, hideSeconds: true});
// '0:01'
prettyMilliseconds(45000, {colonNotation: true, hideSeconds: true});
// '0:00:45'

Shorten Durations For Logs

Choose the number of units that appear in a short log entry. Use verbose when you need full unit names.

prettyMilliseconds(1335669000, {unitCount: 2});
// '15d 11h'
prettyMilliseconds(1335669000, {verbose: true});
// '15 days 11 hours 1 minute 9 seconds'

Format Small Durations

Values below one second appear in milliseconds by default. Use decimal seconds for timer labels or sub-millisecond units for finer measurements.

prettyMilliseconds(900, {subSecondsAsDecimals: true});
// '0.9s'
prettyMilliseconds(100.400080, {formatSubMilliseconds: true});
// '100ms 400µs 80ns'

Configuration Options

• secondsDecimalDigits (number, default 1): Controls the decimal digits in the seconds field. Digits are truncated rather than rounded. For example, 1999ms becomes 1.9s, not 2s.
• millisecondsDecimalDigits (number, default 0): Controls decimal digits in the milliseconds field. Milliseconds are rounded but never reach 1000ms. A nonzero duration below one second never rounds down to a zero millisecond value in this mode.
• keepDecimalsOnWholeSeconds (boolean, default false): Retains trailing decimal zeros on whole seconds, such as 13.0s at the default seconds precision.
• compact (boolean, default false): Shows the first displayed unit only. For example, 1h 10m becomes 1h. It overrides unitCount and sets both decimal-digit options to 0.
• unitCount (number, default Infinity): Limits how many units appear. compact takes precedence, and colonNotation ignores this option.
• verbose (boolean, default false): Uses complete singular or plural unit names, such as 1 minute 5 seconds.
• separateMilliseconds (boolean, default false): Displays milliseconds as their own unit rather than including them in decimal seconds.
• formatSubMilliseconds (boolean, default false): Displays microseconds (µs) and nanoseconds (ns). Values are truncated to whole nanoseconds. Durations below one nanosecond display as 0ms in this mode.
• colonNotation (boolean, default false): Produces clock-style output such as 5:01:45. It sets compact, verbose, separateMilliseconds, and formatSubMilliseconds to false and ignores unitCount. Minutes always appear. Hours also appear when hideSeconds is set. Days following a year field use three digits.
• hideYear (boolean, default false): Expresses years as additional days, using 365 days per year. For example, 1y 3d becomes 368d.
• hideYearAndDays (boolean, default false): Expresses years and days as hours. For example, 1y 3d 5h becomes 8837h.
• hideSeconds (boolean, default false): Omits seconds for durations of at least one minute. Shorter durations retain their seconds. In colon notation, 45000 milliseconds becomes 0:00:45.
• subSecondsAsDecimals (boolean, default false): Shows eligible sub-second values as decimal seconds. For example, 900ms becomes 0.9s, and 999ms also becomes 0.9s at the default precision. Values too small to produce a nonzero seconds digit stay in milliseconds. compact forces zero decimal digits, so sub-second durations stay in milliseconds.

Alternatives & Related Resources

• Convert Human-readable Duration Strings to Milliseconds
• Convert Human Time Formats to Milliseconds in JS – parse-duration
• Relative Time Element for Time Ago Text
• Human-friendly Relative Time Formatter – human-time