Skip to content

Latest commit

 

History

History
516 lines (349 loc) · 13.8 KB

API-reference.md

File metadata and controls

516 lines (349 loc) · 13.8 KB

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.

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

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

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