Skip to main content
The formatMilliseconds() function is a lower-level API for formatting durations. It provides direct access to formatting with explicit language and options parameters.

​
Import

import { formatMilliseconds } from 'enhanced-ms';

​
Signature

function formatMilliseconds(
  milliseconds: number,
  language?: Language,
  options?: FormatOptions | FormatOptionsPreset
): string | null
​
milliseconds
number
required
The duration in milliseconds to format
​
language
Language
default:"getLanguage('en')"
The language settings to use for formatting. Obtain a Language object using getLanguage().
​
options
FormatOptions | FormatOptionsPreset
default:"{}"
Optional settings or preset to customize the output format. See FormatOptions for details.
​
return
string | null
A formatted duration string (e.g., "1 hour, 30 minutes") or null if the duration is invalid

​
Examples

​
Basic usage

import { formatMilliseconds } from 'enhanced-ms';

formatMilliseconds(90061000)
// Returns: "1 day 1 hour 1 minute"

​
With custom language

import { formatMilliseconds, getLanguage } from 'enhanced-ms';

const russian = getLanguage('ru');
formatMilliseconds(90061000, russian)
// Returns: "1 день 1 час 1 минута"

​
With format options

import { formatMilliseconds, getLanguage } from 'enhanced-ms';

const russian = getLanguage('ru');
formatMilliseconds(90061000, russian, { useAbbreviations: true })
// Returns: "1д 1ч 1м"

​
With preset

import { formatMilliseconds } from 'enhanced-ms';

formatMilliseconds(90061000, undefined, 'short')
// Returns: "1d 1h"

formatMilliseconds(90061000, undefined, 'colonNotation')
// Returns: "25:01:01"

formatMilliseconds(90061000, undefined, 'fullPrecision')
// Returns: "1 day 1 hour 1 minute 1 second 0 milliseconds 0 microseconds 0 nanoseconds"

​
Combining language and options

import { formatMilliseconds, getLanguage } from 'enhanced-ms';

const german = getLanguage('de');
formatMilliseconds(90061000, german, {
  useAbbreviations: true,
  unitLimit: 2
})
// Returns: "1T 1Std"

​
Format options

You can customize the output using various options:
  • useAbbreviations - Use short forms (e.g., "1h" instead of "1 hour")
  • unitLimit - Limit the number of units shown
  • includeMs - Include milliseconds in the output
  • includeSubMs - Include microseconds and nanoseconds
  • includeZero - Show units with zero values
  • unitSeparator - Custom separator between units
  • hideUnitNames - Hide unit names (numbers only)
  • minimumDigits - Pad numbers with zeros
See FormatOptions for the complete list.

​
Presets

Three presets are available:
  • 'short' - Abbreviated format with 2 units maximum (e.g., "1m 30s")
  • 'fullPrecision' - Includes milliseconds, microseconds, and nanoseconds
  • 'colonNotation' - Colon-separated time format (e.g., "00:01:30")

​
Return value

The function returns:
  • A formatted string if the duration is valid
  • null if the duration is invalid or results in an empty string

​
Comparison with ms()

While ms() is the recommended way to format durations, formatMilliseconds() is useful when:
  • You need explicit control over the language parameter
  • You’re working with Language objects directly
  • You want to avoid the automatic language resolution of ms()
// Using ms()
import ms from 'enhanced-ms';
ms(90061000, { useAbbreviations: true })

// Using formatMilliseconds()
import { formatMilliseconds, getLanguage } from 'enhanced-ms';
const lang = getLanguage('en');
formatMilliseconds(90061000, lang, { useAbbreviations: true })

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us