Date

The built-in object for working with dates and times. Wraps a single moment in time (milliseconds since Jan 1 1970 UTC) and provides methods to read and format it.

When to use it

Timestamps — recording when something happened
Formatting — displaying dates in human-readable form
Comparisons — checking if one date is before or after another
Arithmetic — adding days, finding differences between dates

Anatomy


const now = new Date()
 
now.getFullYear()     // 2026 — four-digit year
now.getMonth()        // 0-11 — January is 0, not 1
now.getDate()         // 1-31 — day of month
now.getDay()          // 0-6 — day of week, Sunday is 0
now.getHours()        // 0-23
now.getMinutes()      // 0-59
now.getSeconds()      // 0-59
now.getTime()         // 1234567890000 — ms since epoch (Unix timestamp)
 
now.toISOString()     // '2026-02-25T12:00:00.000Z' — ISO 8601 string
now.toLocaleDateString()  // '2/25/2026' — locale-aware date string
now.toLocaleTimeString()  // '12:00:00 PM' — locale-aware time string
 
Date.now()            // ms since epoch — no object needed
Date.parse('2026-01-01') // ms since epoch from a date string

At a glance

Method	What it gives you
`.getFullYear()`	Four-digit year
`.getMonth()`	Month 0–11 (January = 0)
`.getDate()`	Day of month 1–31
`.getDay()`	Day of week 0–6 (Sunday = 0)
`.getHours()` / `.getMinutes()` / `.getSeconds()`	Time components
`.getTime()`	Milliseconds since epoch
`.toISOString()`	ISO 8601 string (UTC)
`.toLocaleDateString()`	Locale-formatted date
`.toLocaleTimeString()`	Locale-formatted time
`Date.now()`	Current ms timestamp (static)
`Date.parse()`	Parse a date string to ms (static)

1. Simple — format a date


const date = new Date('2026-03-15')
 
date.toLocaleDateString('en-US', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
})
// 'Sunday, March 15, 2026'

2. Intermediate — difference in days


const start = new Date('2026-01-01')
const end = new Date('2026-03-01')
 
const ms = end - start                   // dates subtract to ms
const days = Math.floor(ms / 86_400_000) // 86,400,000 ms in a day
days // 59

3. Advanced — relative time formatting


function timeAgo(date) {
  const seconds = Math.floor((Date.now() - date.getTime()) / 1000)
 
  const intervals = [
    { label: 'year', seconds: 31_536_000 },
    { label: 'month', seconds: 2_592_000 },
    { label: 'day', seconds: 86_400 },
    { label: 'hour', seconds: 3_600 },
    { label: 'minute', seconds: 60 },
  ]
 
  for (const { label, seconds: s } of intervals) {
    const count = Math.floor(seconds / s)
    if (count >= 1) return `${count} ${label}${count > 1 ? 's' : ''} ago`
  }
 
  return 'just now'
}
 
timeAgo(new Date(Date.now() - 7_200_000)) // '2 hours ago'

The Intl.RelativeTimeFormat API does this natively with locale support, but building it by hand shows the math.

Gotchas

Month is zero-indexed


new Date(2026, 2, 1) // March 1, not February 1 — month 2 = March
new Date(2026, 0, 1) // January 1 — month 0 = January
 
// if parsing from a 1-based source, subtract 1
const month = 3 // March from an API
new Date(2026, month - 1, 1) // correct

Parsing strings is unreliable


new Date('2026-03-15')   // UTC — midnight in UTC timezone
new Date('03/15/2026')   // local — midnight in your timezone
new Date('March 15 2026') // implementation-dependent — may vary by browser
 
// safest: always use ISO 8601 format or pass numeric arguments
new Date(2026, 2, 15) // explicit, no parsing ambiguity

typeof — typeof new Date() is 'object', use instanceof Date to check