Skip to main content

Format Methods

Format Tokens​

info

Chronos supports a rich set of format tokens that you can use to customize how a date is displayed. These tokens work across format, formatUTC, and formatStrict methods as well as for other methods and utilities like formatDate that accept a format, and behave similarly to libraries like Moment.js or Day.js.

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:

TokenOutputExample
or
Full year2025
or
2-digit year23
Full monthJanuary
Short monthJan
2-digit month01-12
Month1-12
2-digit day01-31
Day1-31
Ordinal day1st, 2nd
Full weekdayMonday
Short weekdayMon
Shorter weekdayMo
24-hour (00-23)09
24-hour (0-23)9
12-hour (01-12)02
12-hour (1-12)2
Minutes (00-59)05
Minutes (0-59)5
Seconds (00-59)09
Seconds (0-59)9
Milliseconds (0-999)9
Milliseconds (000-999)009
AM/PMPM
am/pmpm
TZ Offset ±HH:mm+06:00 or Z (UTC)
Note

  • To output raw text (i.e., not interpreted as a date token), wrap it in square brackets.

  • For example, [Today is] ddd results in Today is Sunday, and YYYY[ year] results in 2025 year.

  • Supported format tokens include: YYYY, YY, MMMM, MMM, MM, M, DD, D, dd, ddd, Do, HH, H, hh, h, mm, m, ss, s, ms, mss, a, A, and ZZ.

  • Any token not wrapped in brackets will be parsed and replaced with its corresponding date component.

format()​

Signature​

format(format?: string, useUTC?: boolean): string

Parameters​

  • format: Format string (default: 'dd, mmm DD, YYYY HH:mm:ss')
  • useUTC: Use UTC time (default: false)

Return Type​

string - Formatted date

Example​

const date = new Chronos('2025-01-15T14:30:00');
date.format('YYYY-MM-DD'); // "2025-01-15"
date.format('ddd, mmmm Do YYYY'); // "Wednesday, January 15th 2025"
date.format('h:mm A'); // "2:30 PM"

formatUTC()​

Signature​

formatUTC(format?: string): string

Parameters​

  • format: Format string (default: 'dd, mmm DD, YYYY HH:mm:ss:mss')

Return Type​

string - Formatted UTC date

Notes​

  • Always uses UTC time regardless of instance configuration

Example​

const date = new Chronos('2025-01-15T14:30:00Z');
date.formatUTC('YYYY-MM-DD HH:mm:ss'); // "2025-01-15 14:30:00"

formatStrict()​

Signature​

formatStrict(format?: StrictFormat, useUTC?: boolean): string

Parameters​

  • format: Predefined strict format
  • useUTC: Use UTC time (default: false)

Return Type​

string - Formatted date

Notes​

  • Provides type-safe formatting with IntelliSense support
  • See StrictFormat type for available formats

Example​

date.formatStrict('YYYY-MM-DD'); // Type-safe format

calendar()​

Signature​

calendar(baseDate?: ChronosInput): string

Parameters​

  • baseDate: Reference date (default: now)

Return Type​

string - Human-readable relative date

Notes​

  • Returns strings like "Today at 3:00 PM", "Yesterday at 2:30 AM"

Example​

const date = new Chronos().subtract(1, 'day');
date.calendar(); // "Yesterday at [time]"

fromNow()​

Note

This method is provided by fromNowPlugin. You must register it using Chronos.use(fromNowPlugin) before calling .fromNow(). Once registered, all Chronos instances will have access to the .fromNow() method.

info
  • This method calculates the elapsed time difference (excludes the end day), consistent with libraries like Day.js and Luxon.
  • If you need an inclusive calendar-style difference (counting both start and end days), adjust one day manually before calling fromNow().
  • The smallest unit included can be customized via the level parameter (from 'year' to 'millisecond').
  • Returns "0 <unit>" if no time difference is detected at the requested precision.

Signature​

fromNow(level?: FromNowUnit, withSuffixPrefix?: boolean, time?: ChronosInput): string

Parameters​

  • level: Smallest unit to include (default: 'second')
  • withSuffixPrefix: Include "ago" or "in" depending on the time direction (default: true)
  • time: Optional comparison time (string, number, Date, or Chronos instance). Defaults to now.

Return Type​

string - Human-readable duration

Type Definition​

/** Name of time unit from `'year'` to `'millisecond'`, excluding `'week'` */
type FromNowUnit = "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond";

Example​

import { fromNowPlugin } from 'nhb-toolbox/plugins/fromNowPlugin';

Chronos.use(fromNowPlugin);

new Chronos().fromNow(); // "0 second ago"
new Chronos().add(3, 'hours').fromNow(); // "in 3 hours"
new Chronos().subtract(2, 'days').fromNow(); // "2 days ago"

new Chronos('2020-03-16').fromNow('day', false, '2025-10-01'); 
// "5 years 6 months 15 days" (exclusive of end day)

new Chronos('2020-03-16').subtract(1, 'day').fromNow('day', false, '2025-10-01'); 
// "5 years 6 months 16 days" (inclusive of end day)

fromNowShort()​

Signature​

fromNowShort(): string

Return Type​

string - Short duration string, from year to second

Notes​

  • Returns strings like "2h ago", "in 5m"

Example​

new Chronos().subtract(150, 'minutes').fromNowShort(); // "2h ago"

getGreeting()​

Note

This method is provided by greetingPlugin. You must register it using Chronos.use(greetingPlugin) before calling .getGreeting(). Once registered, all Chronos instances will have access to the .getGreeting() method.

Returns a time-appropriate greeting message based on configurable time periods. Supports custom messages and time thresholds.

Signature​

getGreeting(configs?: GreetingConfigs): string;

Parameters​

  • configs: Configurations options, e.g. times, msgs.

Return Type​

string - The appropriate greeting message.

Alias​

  • greet is an alias for getGreeting method.

Example​

import { greetingPlugin } from 'nhb-toolbox/plugins/greetingPlugin';

Chronos.use(greetingPlugin);

// Use with default configs
new Chronos().getGreeting(); // Greeting msg e.g. "Good Afternoon!"

// Custom msg and times
new Chronos().getGreeting({
  morningEnds: '10:00',
  noonEnds: '14:00',
  afternoonEnds: '18:00',
  eveningEnds: '22:00',
  midnightMessage: 'Working late?',
  currentTime: '01:30'
});

This method internally uses getGreeting function. For detailed usage please refer to the docs.