API-reference.md

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)
      • ISO 8601 string
      • Unix Timestamp (milliseconds since the Unix Epoch - Jan 1 1970, 12AM UTC)
      • Native Javascript Date object
    • 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)
  • 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)
  • Displaying
    • Format .format(stringWithTokens: string)
      • List of all available formats
    • Difference .diff(compared: Dayjs, unit: string (default: 'milliseconds'), float?: boolean)
    • Unix Timestamp (milliseconds) .valueOf()
    • Unix Timestamp (seconds) .unix()
    • Days in the Month .daysInMonth()
    • As Javascript Date .toDate()
    • As Array .toArray()
    • As JSON .toJSON()
    • As ISO 8601 String .toISOString()
    • As Object .toObject()
    • As String .toString()
  • Query
    • Is Before .isBefore(compared: Dayjs)
    • Is Same .isSame(compared: Dayjs)
    • Is After .isAfter(compared: Dayjs)
    • Is Leap Year .isLeapYear()
  • Plugin APIs
    • RelativeTime

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

Unix Timestamp (milliseconds since the Unix Epoch - Jan 1 1970, 12AM UTC)

dayjs(1318781876406);

Native Javascript Date object

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

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.

dayjs().month();

Day of the Month .date()

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

dayjs().date();

Day of the Week .day()

Returns a number representing the Dayjs's day of the week

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('2000-10-25')
  .set('month', 3)
  .set('year', 2020).toString(); // Sat, 25 Apr 2020 00:00:00 GMT

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
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 Leap Year .isLeapYear()

Returns a boolean indicating whether the Dayjs's year is a leap year or not.

dayjs('2000-01-01').isLeapYear(); // true

Plugin APIs

RelativeTime

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

plugin RelativeTime