Format Date & Time

formatDate

Formats a date into a specified string format using comprehensive formatting tokens.

Signature

formatDate(options?: DateFormatOptions): string

Import

import { formatDate } from "toolbox-x/utils";

Parameter

• options: Options to control date and time formatting.

interface DateFormatOptions {
    /** Date to format, must be parsable by `Date` constructor. Can be string, number or `Date`. Defaults to current time. */
    date?: string | number | Date;
    /** The desired format (Default format is `'dd, mmm DD, YYYY HH:mm:ss'` = `'Sun, Apr 06, 2025 16:11:55'`). */
    format?: SafeFormat; // 21,000+ predefined formats + any string that uses tokens
    /** Whether to use UTC time. Defaults to `false`. */
    useUTC?: boolean;
}

Return Type

string - Formatted date/time string according to the specified format.

Example

Alias

formatDate can also be accessed via the following aliases:

• formatDateTime

See Also

• Chronos format methods for similar date formatting capabilities within the Chronos class.

Format Tokens

Use square brackets ([ ]) to escape literal text. Unescaped characters will be treated as formatting tokens and replaced accordingly.

Below is a list of all supported tokens:

formatDateRelative

Formats a date as a relative time string (e.g., "5m ago", "2h from now"). Falls back to a formatted date string for dates older than 7 days.

Import

import { formatDateRelative } from "toolbox-x/utils";

Signature

formatDateRelative(date: Maybe<DateArgs>, format?: SafeFormat): string

Parameters

• date: The date to format — can be a Date object, a date string, or a timestamp number. If undefined, the current date and time will be used.
• format: Optional format string for dates older than 7 days. Defaults to 'mmm D, yyyy hh:mm a'. Supports the same tokens as formatDate().

Return Type

string - A relative time string if the date is within the last 7 days, otherwise a formatted date string.

Example

Relative Output Ranges

Aliases

formatDateRelative can also be accessed via the following aliases:

• formatRelativeDate
• formatRelativeTime

Notes

• If the provided date is invalid, the function returns 'Invalid Date!'.
• The suffix "ago" or "from now" is determined by whether the date is in the past or future.
• For dates older than 7 days, the output is formatted using the provided format string or the default 'mmm D, yyyy hh:mm a'.

See Also

• formatDate() for full date formatting with custom tokens.

formatTimePart

Formats a time-only string into a formatted time string, automatically combining it with today's date for proper parsing.

Import

import { formatTimePart } from "toolbox-x/utils";

Signature

formatTimePart(time: string, format?: TimeOnlyFormat): string

Parameters

• time: Time string to be formatted. Supported formats include:

  • HH:mm → e.g., '14:50'
  • HH:mm:ss → e.g., '14:50:00'
  • HH:mm:ss.mss → e.g., '14:50:00.800'
  • HH:mm+TimeZoneOffset(HH) → e.g., '14:50+06'
  • HH:mm+TimeZoneOffset(HH:mm) → e.g., '14:50+06:00'
  • HH:mm:ss+TimeZoneOffset(HH) → e.g., '14:50:00+06'
  • HH:mm:ss+TimeZoneOffset(HH:mm) → e.g., '14:50:00+05:30'
  • HH:mm:ss.mss+TimeZoneOffset(HH) → e.g., '14:50:00.800+06'
  • HH:mm:ss.mss+TimeZoneOffset(HH:mm) → e.g., '14:50:00.800+06:30'

  Note: Input defaults to today's date and assumes local timezone if no offset is provided.

• format: Optional format tokens for time part only (default: 'hh:mm:ss a' = '02:33:36 pm').

  • Supports the same time-related tokens as formatDate().

Return Type

string - Formatted time string in local (system) time.

Example

Behavior Details

1. Date Combination: Automatically combines the input time with today's date (using YYYY-MM-DD) to create a complete datetime string for parsing.
2. Timezone Handling:
   • If a timezone offset is provided (e.g., +06:00), it's preserved in the combined datetime
   • If no offset is provided, local system timezone is assumed
3. Normalization: The function internally normalizes various time formats to ISO-like format for consistent parsing
4. Output: Always returns time formatted according to the specified tokens, converted to local system time

Supported Time Format Tokens

The format parameter accepts the same time-related tokens as formatDate():

Use Cases

• Formatting time inputs from forms or APIs that only provide time
• Displaying time-only data in user-friendly formats
• Converting 24-hour time to 12-hour format with AM/PM indicators
• Adjusting times from different timezones to local display

Notes

• This function is ideal when you only have a time component without a specific date
• For complete datetime formatting with specific dates, use formatDate() instead
• The function handles timezone offsets but always outputs in local system time
• Millisecond tokens (ms, mss) are supported but may not show if the input doesn't include milliseconds
• If date formatting tokens are passed, it will output the current date