format()

Token-based date and time formatting for any Temporal object — Moment.js muscle memory, Temporal-native engine.

Signature

function format(
  temporalObj: FormattableTemporalType,
  formatString: string,
  options?: FormatOptions
): string

type FormattableTemporalType =
  | Temporal.PlainDate
  | Temporal.PlainTime
  | Temporal.PlainDateTime
  | Temporal.ZonedDateTime
  | Temporal.Instant

interface FormatOptions {
  /**
   * BCP 47 locale tag used for month and weekday *names* (MMMM, MMM, dddd, ddd).
   * Defaults to the runtime's default locale.
   * @example 'fr', 'es', 'ja', 'de', 'zh-TW'
   */
  locale?: string
}

Token reference

Tokens are matched longest-first (MMMM before MMM before MM before M; Do before DD before D; HH before H), so format strings are never ambiguous. Any sequence that is not a token — including unrecognized letters and all punctuation — is emitted literally.

Date tokens

Token	Example	Description
YYYY	2026	Full 4-digit year
YY	26	2-digit year, zero-padded
MMMM	April	Full month name (locale-aware)
MMM	Apr	Abbreviated month name (locale-aware)
MM	04	Numeric month, zero-padded (01–12)
M	4	Numeric month, no padding (1–12)
Do	9th	Day of month with ordinal suffix
DD	09	Day of month, zero-padded (01–31)
D	9	Day of month, no padding (1–31)
dddd	Thursday	Full weekday name (locale-aware)
ddd	Thu	Abbreviated weekday name (locale-aware)

Time tokens

Token	Example	Description
HH	14	24-hour clock, zero-padded (00–23)
H	14	24-hour clock, no padding (0–23)
hh	02	12-hour clock, zero-padded (01–12)
h	2	12-hour clock, no padding (1–12)
mm	05	Minutes, zero-padded (00–59)
ss	30	Seconds, zero-padded (00–59)
SSS	042	Milliseconds, zero-padded (000–999)
A	PM	AM/PM uppercase
a	pm	am/pm lowercase

Offset & timestamp tokens

Token	Example	Description
Z	+05:30	UTC offset, with colon (ZonedDateTime / Instant only)
ZZ	+0530	UTC offset, no colon
X	1775736000	Unix timestamp in seconds
x	1775736000000	Unix timestamp in milliseconds

Escape syntax

Wrap any literal text in [square brackets] so its characters are never read as tokens — essential for words that contain token letters.

Input	Output
[Today is] dddd	Today is Thursday
h:mm A [at] MMM D	2:05 PM at Apr 9
YYYY-MM-DD[T]HH:mm[Z]	2026-04-09T14:05Z (literal T and Z)

Single letters are tokens. D, M, H, h, A, a, Z, X, x are all interpreted. To print a literal word like Day or a trailing Z, wrap it: [Day], [Z]. There are no m, s, d, or z tokens — those characters pass through untouched.

Which tokens work on which type?

A Temporal object only carries the fields its type makes sense for. Using a token a type can't provide throws a descriptive Error.

Token group	PlainDate	PlainTime	PlainDateTime	ZonedDateTime	Instant¹
Year / month / day	✅	❌	✅	✅	✅
Weekday (dddd ddd)	✅	❌	✅	✅	✅
Time (HH h mm ss SSS A/a)	❌	✅	✅	✅	✅
Offset (Z ZZ)	❌	❌	❌	✅	✅
Timestamp (X x)	❌	❌	❌	✅	✅

¹ An Instant is normalized to a UTC ZonedDateTime before formatting, so every field is available and the offset is always +00:00.

Examples by Temporal type

PlainDate

import { format } from 'moment-less'

const date = Temporal.PlainDate.from('2026-04-09')

format(date, 'YYYY-MM-DD')      // → "2026-04-09"
format(date, 'MMMM Do, YYYY')   // → "April 9th, 2026"
format(date, 'ddd, D MMM YYYY') // → "Thu, 9 Apr 2026"
format(date, 'DD/MM/YYYY')      // → "09/04/2026"

Time tokens (HH, mm, A, …) throw on a PlainDate — there is no clock component.

PlainDateTime

import { format } from 'moment-less'

const dt = Temporal.PlainDateTime.from('2026-04-09T14:05:30.042')

format(dt, 'YYYY-MM-DD[T]HH:mm:ss') // → "2026-04-09T14:05:30"
format(dt, 'MMMM Do, YYYY h:mm A')  // → "April 9th, 2026 2:05 PM"
format(dt, 'dddd [at] H:mm')        // → "Thursday at 14:05"
format(dt, 'HH:mm:ss.SSS')          // → "14:05:30.042"

PlainTime

import { format } from 'moment-less'

const time = Temporal.PlainTime.from('14:05:30')

format(time, 'HH:mm')    // → "14:05"
format(time, 'h:mm A')   // → "2:05 PM"
format(time, 'hh:mm a')  // → "02:05 pm"

Date tokens (YYYY, MMMM, dddd, …) throw on a PlainTime.

ZonedDateTime

import { format } from 'moment-less'

const zdt = Temporal.ZonedDateTime.from('2026-04-09T14:05:30+05:30[Asia/Kolkata]')

format(zdt, 'YYYY-MM-DD HH:mm Z')  // → "2026-04-09 14:05 +05:30"
format(zdt, 'ZZ')                  // → "+0530"
format(zdt, 'MMMM Do, YYYY')       // → "April 9th, 2026"
format(zdt, 'x')                   // → "1775723730000"

Instant

import { format } from 'moment-less'

const inst = Temporal.Instant.from('2026-04-09T08:35:30Z')

// An Instant is always displayed in UTC
format(inst, 'YYYY-MM-DD[T]HH:mm:ssZ') // → "2026-04-09T08:35:30+00:00"
format(inst, 'HH:mm [UTC]')            // → "08:35 UTC"
format(inst, 'X')                      // → "1775723730"

To display an Instant in a specific time zone, convert it first: inst.toZonedDateTimeISO('America/New_York').

Locale option

options.locale affects month names (MMMM, MMM) and weekday names (dddd, ddd). Numeric output — including the Do ordinal suffix and A/a — always renders in English.

import { format } from 'moment-less'

const date = Temporal.PlainDate.from('2026-04-09')

format(date, 'MMMM', { locale: 'fr' })       // → "avril"
format(date, 'dddd', { locale: 'fr' })       // → "jeudi"
format(date, 'dddd D MMMM', { locale: 'ja' })// → "木曜日 9 4月"
format(date, 'MMMM', { locale: 'de' })       // → "April"

Error behavior

format() throws a standard Error with a descriptive message when a token's required field is missing for the given type:

format(Temporal.PlainDate.from('2026-04-09'), 'HH:mm')
// Error: Token "HH" requires an hour field
//        (not available on PlainDate — use PlainDateTime or ZonedDateTime)

Unrecognized sequences are passed through as literal text — format(date, 'Q1') returns "Q1" because Q is not a token.