API Reference

Instead of modifying the native Date.prototype, Day.js creates a wrapper for the Date object, called Dayjs object.

The Dayjs object is immutable, that is, all API operations that change the Dayjs object in some way will return a new instance of it.

API Reference

Parsing

Constructor `dayjs(dateType?: string | number | Date | Dayjs)`

Calling it without parameters returns a fresh Dayjs object with the current date and time.

dayjs()

Day.js also parses other date formats.

ISO 8601 string

dayjs('2018-04-04T16:00:00.000Z')

Native Javascript Date object

dayjs(new Date(2018, 8, 18))

Unix Timestamp (milliseconds)

Returns a Dayjs from a Unix timestamp (milliseconds since the Unix Epoch)

dayjs(1318781876406)

Unix Timestamp (seconds) `.unix(value: number)`

Returns a Dayjs from a Unix timestamp (seconds since the Unix Epoch)

dayjs.unix(1318781876)
dayjs.unix(1318781876.721)

Custom Parse Format

parse custom formats dayjs("12-25-1995", "MM-DD-YYYY") in plugin CustomParseFormat

Clone `.clone() | dayjs(original: Dayjs)`

Returns a cloned Dayjs.

dayjs().clone()
dayjs(dayjs('2019-01-25')) // passing a Dayjs object to a constructor will also clone it

Validation `.isValid()`

Returns a boolean indicating whether the Dayjs's date is valid.

dayjs().isValid()

Get and Set

Year `.year()`

Gets or sets the year.

dayjs().year()
dayjs().year(2000)

Month `.month()`

Gets or sets the month. Starts at 0

dayjs().month()
dayjs().month(0)

Day of the Month `.date()`

Gets or sets the day of the month. Starts at 1

dayjs().date()
dayjs().date(1)

Day of the Week `.day()`

Gets or sets the day of the week. Starts on Sunday with 0

dayjs().day()
dayjs().day(0)

Hour `.hour()`

Gets or sets the hour.

dayjs().hour()
dayjs().hour(12)

Minute `.minute()`

Gets or sets the minute.

dayjs().minute()
dayjs().minute(59)

Second `.second()`

Gets or sets the second.

dayjs().second()
dayjs().second(1)

Millisecond `.millisecond()`

Gets or sets the millisecond.

dayjs().millisecond()
dayjs().millisecond(1)

Get `.get(unit: string)`

Returns a number with information getting from Dayjs object

dayjs().get('month') // start 0
dayjs().get('day')

List of all available units

Unit	Shorthand	Description
`date`		Date of Month
`day`	`d`	Day of Week (Sunday as 0, Saturday as 6)
`month`	`M`	Month (January as 0, December as 11)
`year`	`y`	Year
`hour`	`h`	Hour
`minute`	`m`	Minute
`second`	`s`	Second
`millisecond`	`ms`	Millisecond

Set `.set(unit: string, value: number)`

Returns a Dayjs with the applied changes.

dayjs().set('date', 1)
dayjs().set('month', 3) // April
dayjs().set('second', 30)

Manipulating

Dayjs object can be manipulated in many ways.

dayjs('2019-01-25')
  .add(1, 'day')
  .subtract(1, 'year')
  .toString() // Fri, 26 Jan 2018 00:00:00 GMT

Add `.add(value: number, unit: string)`

Returns a cloned Dayjs with a specified amount of time added.

dayjs().add(7, 'day')

Subtract `.subtract(value: number, unit: string)`

Returns a cloned Dayjs with a specified amount of time subtracted.

dayjs().subtract(7, 'year')

Start of Time `.startOf(unit: string)`

Returns a cloned Dayjs set to the start of the specified unit of time.

dayjs().startOf('week') // Depends on `weekStart` in locale

End of Time `.endOf(unit: string)`

Returns a cloned Dayjs set to the end of the specified unit of time.

dayjs().endOf('month')

Displaying

Format `.format(stringWithTokens: string)`

Returns a string with the Dayjs's formatted date. To escape characters, wrap them in square brackets (e.g. [A] [MM]).

dayjs().format() // current date in ISO8601, without fraction seconds e.g. '2020-04-02T08:02:17-05:00'

dayjs('2019-01-25').format('[YYYY] YYYY-MM-DDTHH:mm:ssZ[Z]') // 'YYYY 2019-01-25T00:00:00-02:00Z'

dayjs('2019-01-25').format('DD/MM/YYYY') // '25/01/2019'

List of all available formats

Format	Output	Description
`YY`	18	Two-digit year
`YYYY`	2018	Four-digit year
`M`	1-12	The month, beginning at 1
`MM`	01-12	The month, 2-digits
`MMM`	Jan-Dec	The abbreviated month name
`MMMM`	January-December	The full month name
`D`	1-31	The day of the month
`DD`	01-31	The day of the month, 2-digits
`d`	0-6	The day of the week, with Sunday as 0
`dd`	Su-Sa	The min name of the day of the week
`ddd`	Sun-Sat	The short name of the day of the week
`dddd`	Sunday-Saturday	The name of the day of the week
`H`	0-23	The hour
`HH`	00-23	The hour, 2-digits
`h`	1-12	The hour, 12-hour clock
`hh`	01-12	The hour, 12-hour clock, 2-digits
`m`	0-59	The minute
`mm`	00-59	The minute, 2-digits
`s`	0-59	The second
`ss`	00-59	The second, 2-digits
`SSS`	000-999	The millisecond, 3-digits
`Z`	+05:00	The offset from UTC
`ZZ`	+0500	The offset from UTC, 2-digits
`A`	AM PM
`a`	am pm

More available formats Q Do k kk X x ... in plugin AdvancedFormat
Localized format options L LT LTS ... in plugin LocalizedFormat

Difference `.diff(compared: Dayjs, unit?: string, float?: boolean)`

Returns a number indicating the difference of two Dayjss in the specified unit.

const date1 = dayjs('2019-01-25')
const date2 = dayjs('2018-06-05')
date1.diff(date2) // 20214000000 default milliseconds
date1.diff(date2, 'month') // 7
date1.diff(date2, 'month', true) // 7.645161290322581
date1.diff(date2, 'day') // 233

Unix Timestamp (milliseconds) `.valueOf()`

Returns the number of milliseconds since the Unix Epoch for the Dayjs.

dayjs('2019-01-25').valueOf() // 1548381600000

Unix Timestamp (seconds) `.unix()`

Returns the number of seconds since the Unix Epoch for the Dayjs.

dayjs('2019-01-25').unix() // 1548381600

UTC Offset (minutes) `.utcOffset()`

Returns the UTC offset in minutes for the Dayjs.

dayjs().utcOffset()

Days in the Month `.daysInMonth()`

Returns the number of days in the Dayjs's month.

dayjs('2019-01-25').daysInMonth() // 31

As Javascript Date `.toDate()`

Returns a copy of the native Date object parsed from the Dayjs object.

dayjs('2019-01-25').toDate()

As JSON `.toJSON()`

Returns the Dayjs formatted in an ISO8601 string.

dayjs('2019-01-25').toJSON() // '2019-01-25T02:00:00.000Z'

As ISO 8601 String `.toISOString()`

Returns the Dayjs formatted in an ISO8601 string.

dayjs('2019-01-25').toISOString() // '2019-01-25T02:00:00.000Z'

As String `.toString()`

Returns a string representation of the date.

dayjs('2019-01-25').toString() // 'Fri, 25 Jan 2019 02:00:00 GMT'

Query

Is Before `.isBefore(compared: Dayjs, unit?: string)`

Returns a boolean indicating whether the Dayjs's date is before the other supplied Dayjs's.

dayjs().isBefore(dayjs()) // false
dayjs().isBefore(dayjs(), 'year') // false

Is Same `.isSame(compared: Dayjs, unit?: string)`

Returns a boolean indicating whether the Dayjs's date is the same as the other supplied Dayjs's.

dayjs().isSame(dayjs()) // true
dayjs().isSame(dayjs(), 'year') // true

Is After `.isAfter(compared: Dayjs, unit?: string)`

Returns a boolean indicating whether the Dayjs's date is after the other supplied Dayjs's.

dayjs().isAfter(dayjs()) // false
dayjs().isAfter(dayjs(), 'year') // false

Is a Dayjs `.isDayjs(compared: any)`

Returns a boolean indicating whether a variable is a dayjs object or not.

dayjs.isDayjs(dayjs()) // true
dayjs.isDayjs(new Date()) // false

The operator instanceof works equally well:

dayjs() instanceof dayjs // true

UTC

If you want to parse or display in UTC, you can use .utc .local .isUTC with plugin UTC

Plugin APIs

RelativeTime

.from .to .fromNow .toNow to get relative time

plugin RelativeTime

IsLeapYear

.isLeapYear to get is a leap year or not

plugin IsLeapYear

WeekOfYear

.week to get week of the year

plugin WeekOfYear

WeekDay

.weekday to get or set locale aware day of the week

plugin WeekDay

IsoWeeksInYear

.isoWeeksInYear to get the number of weeks in year

plugin IsoWeeksInYear

IsSameOrAfter

.isSameOrAfter to check if a date is same of after another date

plugin IsSameOrAfter

IsSameOrBefore

.isSameOrBefore to check if a date is same of before another date.

plugin IsSameOrBefore

IsBetween

.isBetween to check if a date is between two other dates

plugin IsBetween

QuarterOfYear

.quarter to get quarter of the year

plugin QuarterOfYear

ToArray

.toArray to return an array that mirrors the parameters

plugin ToArray

ToObject

.toObject to return an object with the date's properties

plugin ToObject

MinMax

.min .max to compare given dayjs instances

plugin MinMax

Calendar

.calendar to display calendar time

plugin Calendar

Files

API-reference.md

Latest commit

History

API-reference.md

File metadata and controls

API Reference

Parsing

Constructor dayjs(dateType?: string | number | Date | Dayjs)

ISO 8601 string

Native Javascript Date object

Unix Timestamp (milliseconds)

Unix Timestamp (seconds) .unix(value: number)

Custom Parse Format

Clone .clone() | dayjs(original: Dayjs)

Validation .isValid()

Get and Set

Year .year()

Month .month()

Day of the Month .date()

Day of the Week .day()

Hour .hour()

Minute .minute()

Second .second()

Millisecond .millisecond()

Get .get(unit: string)