Date & Time
formatDate
Format a date value using a custom format pattern.
Parameters
Parameter | Type | Required | Description |
date | Date | string | number | Yes | Date object, epoch timestamp (ms), or stringified number |
formatStr | string | Yes | Format pattern (date-fns tokens) |
Returns: Formatted date string, empty string if invalid
Examples
Common Patterns
Pattern | Output |
dd-MM-yyyy | 26-10-2025 |
MM/dd/yyyy | 10/26/2025 |
yyyy-MM-dd | 2025-10-26 |
MMM dd, yyyy | Oct 26, 2025 |
dd/MM/yyyy HH:mm | 26/10/2025 14:30 |
h:mm a | 2:30 PM |
formatDateByFormatType
Format dates using predefined format types. Includes relative time formatting ("2 hours ago").
Parameters
Parameter | Type | Required | Default | Description |
date | Date | string | number | Yes | - | Date object, epoch timestamp (ms), or stringified number |
formatType | string | No | 'mdyhm' | Predefined format type or custom pattern |
options | FormatDistanceOptions | No | - | Options for relative-time-to-now only |
Format Types
Type | Output Example |
mdyhm (default) | 10/26/2025 14:30 |
dmyhms | 26 Oct 2025, 14:30:45 |
yyyyMMdd | 2025-10-26 |
iso | 2025-10-26T14:30:45+00:00 |
relative-time-to-now | 2 hours ago |
Examples
formatTime
Convert milliseconds into a human-readable duration (e.g., "1h 30m 15s").
Parameters
Parameter | Type | Required | Default | Description |
ms | number | Yes | - | Duration in milliseconds |
precision | 'years' | 'months' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds' | No | 'milliseconds' | Lowest time unit to display |
notation | 'comfortable' | 'compact' | No | 'compact' | 'compact' : "1h 30m", 'comfortable' : "1 hour 30 minutes" |
maxSignificantUnits | number | No | 7 | Max number of units to show |
Examples
Numbers
formatNumber
Format numbers with locale support, compact notation (1.2K, 3.4M), and units.
Parameters
Single object parameter with these properties:
Property | Type | Required | Description |
value | number | Yes | Number to format |
locale | string | No | Locale (e.g., 'en-US', 'de-DE') |
maximumFractionDigits | number | No | Max decimal places |
notation | 'standard' | 'scientific' | 'compact' | 'text' | No | Format style (default: 'standard') |
compactDisplay | 'short' | 'long' | No | For compact: 'short' = "1.5K", 'long' = "1.5 thousand" |
unit | string | No | Unit (e.g., 'percent', 'kilometer', 'byte') |
unitDisplay | 'short' | 'long' | No | Unit display style |
padDecimalPlaces | boolean | No | Pad decimals (5.5 → 5.50) |
Examples
Common Units
Category | Units |
Length | meter kilometer mile |
Mass | kilogram pound |
Temperature | celsius fahrenheit |
Digital | byte kilobyte megabyte gigabyte |
Other | percent |
JSON
parseJson
Safely parse JSON strings. Never throws errors—returns fallback value on failure.
Parameters
Parameter | Type | Required | Default | Description |
str | string | Yes | - | JSON string to parse |
fallback | T | No | {} | Value returned if parsing fails |
retriever | function | No | - | Custom reviver function |
Examples
stringifyJson
Safely convert objects to JSON strings. Never throws errors—returns fallback on failure (e.g., circular references).
Parameters
Parameter | Type | Required | Default | Description |
obj | unknown | Yes | - | Object to stringify |
fallback | T | No | null | Value returned if stringify fails |
space | number | No | 0 | Spaces for indentation (pretty print) |
replacer | function | No | - | Custom replacer function |
Examples
Reference
Format Type Reference
Complete list of formatDateByFormatTypeformat types:
Type | Pattern | Example |
mdyhm | MM/dd/yyyy H:mm | 10/26/2025 14:30 |
dmyhms | dd MMM yyyy, H:mm:ss | 26 Oct 2025, 14:30:45 |
dmhms | dd MMM, H:mm:ss | 26 Oct, 14:30:45 |
dmyhma | dd MMM yyyy, H:mm a | 26 Oct 2025, 2:30 PM |
dmyhm | dd MMM yyyy, H:mm | 26 Oct 2025, 14:30 |
mdyhma | MMM dd, yyyy h:mm a | Oct 26, 2025 2:30 PM |
mdhma | MMM dd, h:mma | Oct 26, 2:30PM |
Mdy | MMMM dd, yyyy | October 26, 2025 |
dMy | d MMM yyyy | 26 Oct 2025 |
yyyyMMdd | yyyy-MM-dd | 2025-10-26 |
ddMMyyyy | dd-MM-yyyy | 26-10-2025 |
ddMMyyyyhma | dd-MM-yyyy h:mm a | 26-10-2025 2:30 PM |
ddMMM | dd MMM | 26 Oct |
iso | yyyy-MM-dd'T'HH:mm:ssxxx | 2025-10-26T14:30:45+00:00 |
hma | h:mm a | 2:30 PM |
DayMMddyyyy | EEEE, MM-dd-yyyy | Sunday, 10-26-2025 |
relative-time-to-now | - | 2 hours ago |