date-fns Cheatsheet

Table of Contents

1. Installation
2. Parsing
3. Formatting
4. Manipulating
5. Comparing
6. Getting and Setting
7. Time Zones
8. Intervals
9. Duration
10. Utility Functions

Installation

Install date-fns:

npm install date-fns

Parsing

Parse strings into Date objects:

import { parse, parseISO } from 'date-fns'

// Parse a string with a specific format
const date1 = parse('2021-01-01', 'yyyy-MM-dd', new Date())

// Parse an ISO 8601 string
const date2 = parseISO('2021-01-01T00:00:00.000Z')

Formatting

Format Date objects into strings:

import { format } from 'date-fns'

const date = new Date(2021, 0, 1)

// Basic formatting
console.log(format(date, 'yyyy-MM-dd')) // '2021-01-01'

// Complex formatting
console.log(format(date, "EEEE, MMMM do 'at' h:mm a")) // 'Friday, January 1st at 12:00 AM'

// Localized formatting
import { fr } from 'date-fns/locale'
console.log(format(date, "d MMMM yyyy", { locale: fr })) // '1 janvier 2021'

Manipulating

Add or subtract time from dates:

import { addDays, subMonths, setYear } from 'date-fns'

const date = new Date(2021, 0, 1)

// Add 7 days
const newDate1 = addDays(date, 7)

// Subtract 3 months
const newDate2 = subMonths(date, 3)

// Set the year to 2022
const newDate3 = setYear(date, 2022)

Comparing

Compare dates:

import { isAfter, isBefore, isEqual, differenceInDays } from 'date-fns'

const date1 = new Date(2021, 0, 1)
const date2 = new Date(2021, 6, 1)

console.log(isAfter(date2, date1)) // true
console.log(isBefore(date1, date2)) // true
console.log(isEqual(date1, date2)) // false

// Get the number of days between two dates
console.log(differenceInDays(date2, date1)) // 181

Getting and Setting

Get or set components of a date:

import { getYear, getMonth, setDate, setHours } from 'date-fns'

const date = new Date(2021, 0, 1, 12, 0)

console.log(getYear(date)) // 2021
console.log(getMonth(date)) // 0 (January)

const newDate1 = setDate(date, 15) // Set day of month to 15
const newDate2 = setHours(date, 14) // Set hour to 14 (2 PM)

Time Zones

Working with time zones (requires date-fns-tz package):

import { zonedTimeToUtc, utcToZonedTime, format } from 'date-fns-tz'

const date = new Date('2021-01-01T00:00:00.000Z')
const timeZone = 'America/New_York'

// Convert UTC time to a specific time zone
const nyDate = utcToZonedTime(date, timeZone)

// Format the date, showing the time zone name
console.log(format(nyDate, 'yyyy-MM-dd HH:mm:ss zzz', { timeZone }))
// '2020-12-31 19:00:00 EST'

// Convert a zoned time to UTC
const utcDate = zonedTimeToUtc(nyDate, timeZone)

Intervals

Work with time intervals:

import { intervalToDuration, eachDayOfInterval } from 'date-fns'

const start = new Date(2021, 0, 1)
const end = new Date(2021, 11, 31)

// Get the duration of an interval
const duration = intervalToDuration({ start, end })
console.log(duration) // { years: 0, months: 11, days: 30, hours: 0, ... }

// Get an array of all days in an interval
const days = eachDayOfInterval({ start, end })

Duration

Work with durations:

import { add, formatDuration } from 'date-fns'

const date = new Date(2021, 0, 1)

// Add a duration to a date
const newDate = add(date, { years: 1, months: 2, days: 3 })

// Format a duration
console.log(formatDuration({ years: 2, months: 9, days: 1 }))
// '2 years 9 months 1 day'

Utility Functions

Other useful functions:

import { isLeapYear, getDaysInMonth, startOfWeek, endOfMonth } from 'date-fns'

const date = new Date(2021, 1, 1) // February 1, 2021

console.log(isLeapYear(date)) // false
console.log(getDaysInMonth(date)) // 28

const weekStart = startOfWeek(date)
const monthEnd = endOfMonth(date)