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(existing?: 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);

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()`

Returns a number representing the Dayjs's year.

dayjs().year();

Month `.month()`

Returns a number representing the Dayjs's month. Starts at 0

dayjs().month();

Day of the Month `.date()`

Returns a number representing the Dayjs's day of the month. Starts at 1

dayjs().date();

Day of the Week `.day()`

Returns a number representing the Dayjs's day of the week. Starts on Sunday with 0

dayjs().day();

Hour `.hour()`

Returns a number representing the Dayjs's hour.

dayjs().hour();

Minute `.minute()`

Returns a number representing the Dayjs's minute.

dayjs().minute();

Second `.second()`

Returns a number representing the Dayjs's second.

dayjs().second();

Millisecond `.millisecond()`

Returns a number representing the Dayjs's millisecond.

dayjs().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);

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
`year`	`y`	Year
`hour`	`h`	Hour
`minute`	`m`	Minute
`second`	`s`	Second
`millisecond`	`ms`	Millisecond

Manipulating

Dayjs objects 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');

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 or culy brackets (e.g. [G] {um}).

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

dayjs('2019-01-25').format('{YYYY} MM-DDTHH:mm:ssZ[Z]'); // '{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`	+5: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

Difference `.diff(compared: Dayjs, unit: string (default: 'milliseconds'), 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
date1.diff(date2, 'months'); // 7
date1.diff(date2, 'months', true); // 7.645161290322581
date1.diff(date2, 'days'); // 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

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 Array `.toArray()`

Returns an array that mirrors the parameters from new Date().

dayjs('2019-01-25').toArray(); // [ 2019, 0, 25, 0, 0, 0, 0 ]

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 Object `.toObject()`

Returns an object with the date's properties.

dayjs('2019-01-25').toObject();
/* { years: 2019,
     months: 0,
     date: 25,
     hours: 0,
     minutes: 0,
     seconds: 0,
     milliseconds: 0 } */

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)`

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

dayjs().isBefore(dayjs()); // false

Is Same `.isSame(compared: Dayjs)`

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

dayjs().isSame(dayjs()); // true

Is After `.isAfter(compared: Dayjs)`

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

dayjs().isAfter(dayjs()); // 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

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

IsBetween

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

plugin IsBetween

FilesExpand file tree

API-reference.md

Latest commit

History

API-reference.md

File metadata and controls

API Reference

Parsing

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

ISO 8601 string

Native Javascript Date object

Unix Timestamp (milliseconds)

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

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()

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

List of all available units

Manipulating

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

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

Start of Time .startOf(unit: string)

End of Time .endOf(unit: string)