Interface: FormatDurationOptions

Defined in: utils/date/formatDuration.ts:33

Options for formatDuration.

Properties

inputUnit?

optional inputUnit: "milliseconds" | "seconds"

Defined in: utils/date/formatDuration.ts:40

Unit of the duration argument.

• "milliseconds" (default) — duration is the number of milliseconds.
• "seconds" — duration is the number of seconds.

---

minUnit?

optional minUnit: DurationUnit

Defined in: utils/date/formatDuration.ts:53

Smallest time unit to include in the formatted string.

Units smaller than this are discarded (truncated, not rounded).

Examples:

• minUnit: 'second' + 1500 ms → "1 second" (milliseconds dropped)
• minUnit: 'minute' + 90 seconds → "1 minute" (seconds dropped)

Defaults to "second".

---

maxUnit?

optional maxUnit: DurationUnit

Defined in: utils/date/formatDuration.ts:63

Largest time unit to include in the formatted string.

Units larger than this are not used. For example, if you set maxUnit: 'hour', days will be converted to hours.

Defaults to "day".

---

includeZeroUnits?

optional includeZeroUnits: boolean

Defined in: utils/date/formatDuration.ts:71

Whether to include units with a value of 0.

• When false (default): "1 hour 0 minutes" → "1 hour".
• When true: "1 hour 0 minutes".

---

largestUnitOnly?

optional largestUnitOnly: boolean

Defined in: utils/date/formatDuration.ts:82

Whether to only display the single largest non-zero unit.

• false (default): 90_000 ms → "1 minute 30 seconds"
• true: 90_000 ms → "1 minute"

Note: If the duration is exactly 0, this still returns "0 <minUnit>" (e.g. "0 seconds").

---

separator?

optional separator: string

Defined in: utils/date/formatDuration.ts:91

String used to join each segment in the final result.

Example: "1 hour, 5 minutes" → separator: ', '.

Default: ' ' (single space).

---

labels?

optional labels: FormatDurationLabels

Defined in: utils/date/formatDuration.ts:109

Custom label overrides for each unit.

For example:

formatDuration(90_000, {
  labels: {
    minute: 'min',
    minutePlural: 'min',
    second: 's',
    secondPlural: 's',
  },
});
// → "1 min 30 s"

---

formatUnit()?

optional formatUnit: (unit, value) => string

Defined in: utils/date/formatDuration.ts:127

Custom formatter for each (unit, value) pair.

When provided, this takes precedence over labels.

Example:

formatDuration(90_000, {
  formatUnit: (unit, value) => {
    const short = { minute: 'm', second: 's' } as const;
    return `${value}${short[unit] ?? unit}`;
  },
});
// → "1m 30s"

Parameters

unit

DurationUnit

value

number

Returns

string

---

signDisplay?

optional signDisplay: "auto" | "always" | "never"

Defined in: utils/date/formatDuration.ts:136

How to display the sign for negative durations.

• "auto" (default): '-' for negative, nothing for positive/zero.
• "always": '+' for positive, '-' for negative.
• "never": always omit sign (absolute value).