Date

Added in ves1 · Updated March 14, 2026 · Built-in Objects

javascript date es1

The Date object is a built-in JavaScript object that represents dates and times. It provides methods for creating, parsing, manipulating, and formatting dates across different time zones and formats.

Creating Date Objects

Create a Date instance using the Date constructor:

// Current date and time
const now = new Date();
// 2026-03-14T06:38:00.000Z

// From a date string
const fromString = new Date("2026-03-14T12:00:00Z");
// 2026-03-14T12:00:00.000Z

// From year, month (0-indexed), day, hour, minute, second, millisecond
const fromParts = new Date(2026, 2, 14, 12, 0, 0, 0);
// 2026-03-14T11:00:00.000Z (local time)

// From a timestamp (milliseconds since Unix epoch)
const fromTimestamp = new Date(1700000000000);
// 2023-11-14T22:13:20.000Z

Static Methods

Date.now()

Returns the current timestamp in milliseconds:

Date.now()   // 1700000000000 (current timestamp)

Date.parse()

Parses a date string and returns a timestamp:

Date.parse("2026-03-14")   // 1736726400000 (midnight UTC)

Date.UTC()

Returns the timestamp for a UTC date:

Date.UTC(2026, 2, 14)   // 1736726400000

Date.prototype.toISOString()

Formats the date as an ISO 8601 string:

const date = new Date(2026, 2, 14, 12, 0, 0);
date.toISOString()   // "2026-03-14T11:00:00.000Z"

Getting Date Components

Extract individual components from a Date:

const date = new Date("2026-03-14T12:30:45.123Z");

date.getFullYear()         // 2026
date.getMonth()            // 2 (March, 0-indexed)
date.getDate()             // 14 (day of month)
date.getDay()              // 6 (Saturday, 0 = Sunday)
date.getHours()            // 12
date.getMinutes()          // 30
date.getSeconds()          // 45
date.getMilliseconds()     // 123
date.getTime()             // 1736701845123 (timestamp)

// UTC variants
date.getUTCFullYear()      // 2026
date.getUTCMonth()         // 2
date.getUTCDate()          // 14

Setting Date Components

Modify specific components of a Date:

const date = new Date("2026-03-14T12:00:00Z");

date.setFullYear(2027)           // Updates year
date.setMonth(0)                 // Sets to January
date.setDate(1)                  // Sets to 1st of month
date.setHours(23)                // Sets hour to 23
date.setMinutes(59)               // Sets minutes
date.setSeconds(0)                // Clears seconds
date.setMilliseconds(500)        // Sets milliseconds
date.setTime(1736726400000)      // Sets from timestamp

Date Arithmetic

Perform calculations with dates:

const start = new Date("2026-01-01");
const end = new Date("2026-12-31");

// Difference in milliseconds
const diff = end - start;
// 364 * 24 * 60 * 60 * 1000 = 31449600000

// Add days to a date
function addDays(date, days) {
  const result = new Date(date);
  result.setDate(result.getDate() + days);
  return result;
}

addDays(new Date("2026-03-14"), 7)   // 2026-03-21

Formatting

Format dates for display:

const date = new Date("2026-03-14T12:30:00Z");

date.toString()         
// "Sat Mar 14 2026 12:30:00 GMT+0000"

date.toDateString()     
// "Sat Mar 14 2026"

date.toTimeString()     
// "12:30:00 GMT+0000"

date.toISOString()      
// "2026-03-14T12:30:00.000Z"

date.toLocaleString()   
// "3/14/2026, 12:30:00 PM" (locale-dependent)

date.toLocaleDateString()
// "3/14/2026"

date.toLocaleTimeString()
// "12:30:00 PM"

Working with Time Zones

Handle different time zones:

const date = new Date("2026-03-14T12:00:00Z");

// Get timezone offset in minutes
date.getTimezoneOffset()   // 0 for UTC

// Using Intl for locale-aware formatting
const formatter = new Intl.DateTimeFormat("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "2-digit",
  minute: "2-digit",
  timeZoneName: "short"
});

formatter.format(date)   // "March 14, 2026, 12:00 PM UTC"

Relative Time

Create relative time displays:

function relativeTime(date) {
  const now = Date.now();
  const diff = now - date.getTime();
  
  const seconds = Math.floor(diff / 1000);
  const minutes = Math.floor(seconds / 60);
  const hours = Math.floor(minutes / 60);
  const days = Math.floor(hours / 24);
  
  if (days > 0) return `${days} day${days > 1 ? "s" : ""} ago`;
  if (hours > 0) return `${hours} hour${hours > 1 ? "s" : ""} ago`;
  if (minutes > 0) return `${minutes} minute${minutes > 1 ? "s" : ""} ago`;
  return `${seconds} seconds ago`;
}

relativeTime(new Date(Date.now() - 3600000))   // "1 hour ago"

Parsing Dates

Safely parse dates from user input:

function parseDate(input) {
  const date = new Date(input);
  if (isNaN(date.getTime())) {
    return null; // Invalid date
  }
  return date;
}

parseDate("2026-03-14")      // Valid Date
parseDate("invalid")         // null
parseDate("2026-13-45")      // null