Getting started
Introduction
Moment.js parses, formats, and manipulates dates. It is a legacy project in maintenance mode: fine for existing code, discouraged for new projects.
- Moment.js documentation (momentjs.com)
- Project status (momentjs.com)
Maintenance status
Moment 2.31.0 is the current release. The project adds no new user-facing features, keeps the mutable API, and prioritizes compatibility over bug fixes. The maintainers recommend other libraries for new code.
See: Project status
Moving off Moment
Core API
Parsing
moment() // now
moment('2013-03-01') // ISO 8601
moment('2013-03-01', 'YYYY-MM-DD') // with a format
moment('2013-03-01', 'YYYY-MM-DD', true) // strict
moment.unix(1362096000) // seconds
moment.utc('2013-03-01T00:00:00Z') // UTC mode
Pass true for strict parsing of user input. Without a format, non-ISO strings fall back to Date and warn.
See: Parsing
Display
m.format() // ISO 8601 with offset
m.format('dddd') // "Friday"
m.format('MMM Do YY') // "Mar 1st 13"
m.fromNow() // "7 years ago"
m.calendar() // "03/01/2013"
m.diff(other, 'days') // whole days
m.unix() // seconds
m.valueOf() // milliseconds
diff() truncates toward zero; add true as a third argument for a float.
See: Format
Manipulating
m.add(1, 'day')
m.subtract(2, 'days')
m.startOf('day')
m.endOf('month')
Moment objects are mutable: add() and startOf() return the same instance. Call m.clone() before branching.
See: Manipulating
Querying
m.isValid()
m.isBefore(other)
m.isAfter(other)
m.isSame(other, 'day')
m.isBetween(from, to, 'day')
m.isSameOrBefore(other)
isSame() and isBetween() take a unit to pin the comparison to that granularity.
See: Query
Durations
const d = moment.duration(2, 'days')
d.asHours() // 48
d.humanize() // "2 days"
moment.duration(90, 'minutes').humanize() // "an hour"
Durations convert units, and can be passed to m.add(d) or m.subtract(d).
See: Durations
Internationalization
Locale formats
.format('L') // 06/09/2014
.format('l') // 6/9/2014
.format('LL') // June 9 2014
.format('ll') // Jun 9 2014
.format('LLL') // June 9 2014 9:32 PM
.format('lll') // Jun 9 2014 9:32 PM
.format('LLLL') // Monday, June 9 2014 9:32 PM
.format('llll') // Mon, Jun 9 2014 9:32 PM
The L tokens follow the active locale, so date order adapts to each language.
See: Format
Locales
import 'moment/locale/fr' // registers French
moment.locale('fr') // switches globally
m.locale('de') // switches one instance
Locales are not bundled by default in Node; import each one you need. Bundlers include all of them unless filtered.
See: i18n
Time zones
import moment from 'moment-timezone'
moment.tz('2024-06-01 12:00', 'America/New_York')
moment.tz.guess()
moment.utc().tz('Europe/Paris')
Time zones live in the separate moment-timezone package, which bundles IANA data.
See: Moment Timezone
Formatting
Examples
Date
| Example | Output |
|---|---|
YYYY-MM-DD | 2014-01-01 |
dddd, MMMM Do YYYY | Friday, May 16th 2014 |
dddd [the] Do [of] MMMM | Friday the 16th of May |
Time
| Example | Output |
|---|---|
hh:mm a | 12:30 pm |
Moment.js tokens; date-fns and Java SimpleDateFormat use different ones. Moment itself is in maintenance mode.
See: Format
Date
| Symbol | Example | Area |
|---|---|---|
d | 0..6 | Weekday |
dd | Su | |
ddd | Sun | |
dddd | Sunday | |
YY | 13 | Year |
YYYY | 2013 | |
M | 1..12 (Jan is 1) | Month |
Mo | 1st..12th | |
MM | 01..12 (Jan is 1) | |
MMM | Jan | |
MMMM | January | |
Q | 1..4 | Quarter |
Qo | 1st..4th | |
D | 1..31 | Day |
Do | 1st..31st | |
DD | 01..31 | |
DDD | 1..365 | Day of year |
DDDo | 1st..365th | |
DDDD | 001..365 | |
w | 1..53 | Week of year |
wo | 1st..53rd | |
ww | 01..53 |
See: Format
Time
| Symbol | Example | Area |
|---|---|---|
H | 0..23 | 24h hour |
HH | 00..23 | |
h | 1..12 | 12h hour |
hh | 01..12 | |
m | 0..59 | Minutes |
mm | 00..59 | |
s | 0..59 | Seconds |
ss | 00..59 | |
a | am | AM/PM |
A | AM | |
Z | +07:00 | Zone offset |
ZZ | +0730 | |
S | 0..9 | Deciseconds |
SS | 00..99 | Centiseconds |
SSS | 000..999 | Milliseconds |
X | 1360013296 | Unix timestamp |
x | 1360013296123 | Unix ms timestamp |
See: Format
Presets
| Example | Output |
|---|---|
LT | 8:30 PM |
LTS | 8:30:25 PM |
LL | August 2, 1985 |
ll | Aug 2, 1985 |
LLL | August 2, 1985 8:30 PM |
lll | Aug 2, 1985 8:30 PM |
LLLL | Friday, August 2, 1985 8:30 PM |
llll | Fri, Aug 2, 1985 8:30 PM |
See: Long date formats
References
- Moment.js docs (momentjs.com)
- Moment Timezone docs (momentjs.com)
- Project status (momentjs.com)
- Datetime cheatsheet (devhints.io)
0 Comments for this cheatsheet. Write yours!