Luxon Manual Reference
import DateTime from 'luxon/src/datetime.js'
public class | source

DateTime

A DateTime is an immutable data structure representing a specific date and time and accompanying methods. It contains class and instance methods for creating, parsing, interrogating, transforming, and formatting them.

A DateTime comprises of:

  • A timestamp. Each DateTime instance refers to a specific millisecond of the Unix epoch.
  • A time zone. Each instance is considered in the context of a specific zone (by default the local system's zone).
  • Configuration properties that effect how output strings are formatted, such as locale, numberingSystem, and outputCalendar.

Here is a brief overview of the most commonly used functionality it provides:

There's plenty others documented below. In addition, for more information on subtler topics like internationalization, time zones, alternative calendars, validity, and so on, see the external documentation.

Static Member Summary

Static Public Members
public static get

toLocaleString format like 'October 14, 1983, 9:30 AM EDT'.

public static get

toLocaleString format like 'October 14, 1983, 9:30:33 AM EDT'.

public static get

toLocaleString format like 'Friday, October 14, 1983, 9:30 AM Eastern Daylight Time'.

public static get

toLocaleString format like 'Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time'.

public static get

toLocaleString format like 'Oct 14, 1983, 9:30 AM'.

public static get

toLocaleString format like 'Oct 14, 1983, 9:30:33 AM'.

public static get

toLocaleString format like '10/14/1983, 9:30 AM'.

public static get

toLocaleString format like '10/14/1983, 9:30:33 AM'.

public static get

toLocaleString format like 'October 14, 1983'

public static get

toLocaleString format like 'Tuesday, October 14, 1983'

public static get

toLocaleString format like 'Oct 14, 1983'

public static get

toLocaleString format like 10/14/1983

public static get

toLocaleString format like '09:30', always 24-hour.

public static get

toLocaleString format like '09:30:23 Eastern Daylight Time', always 24-hour.

public static get

toLocaleString format like '09:30:23', always 24-hour.

public static get

toLocaleString format like '09:30:23 EDT', always 24-hour.

public static get

toLocaleString format like '09:30 AM'.

public static get

toLocaleString format like '09:30:23 AM Eastern Daylight Time'.

public static get

toLocaleString format like '09:30:23 AM'.

public static get

toLocaleString format like '09:30:23 AM EDT'.

Static Method Summary

Static Public Methods
public static

fromFormat(text: string, fmt: string, options: Object): DateTime

Create a DateTime from an input string and format string Defaults to en-US if no locale has been specified, regardless of the system's locale

public static

fromFormatExplain(text: string, fmt: string, options: Object): Object

Explain how a string would be parsed by fromFormat()

public static

fromHTTP(text: string, options: Object): DateTime

Create a DateTime from an HTTP header date

public static

fromISO(text: string, opts: Object): DateTime

Create a DateTime from an ISO 8601 string

public static

fromJSDate(date: Date, options: Object): DateTime

Create a DateTime from a Javascript Date object.

public static

fromMillis(milliseconds: number, options: Object): DateTime

Create a DateTime from a number of milliseconds since the epoch (i.e.

public static

Create a DateTime from a Javascript object with keys like 'year' and 'hour' with reasonable defaults.

public static

Create a DateTime from an RFC 2822 string

public static

fromSQL(text: string, options: Object): DateTime

Create a DateTime from a SQL date, time, or datetime Defaults to en-US if no locale has been specified, regardless of the system's locale

public static

fromString(text: *, fmt: *, opts: {}): *

this method was deprecated. use fromFormat instead
public static

fromStringExplain(text: *, fmt: *, options: {}): *

this method was deprecated. use fromFormatExplain instead
public static

invalid(reason: *): DateTime

Create an invalid DateTime.

public static

local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime

Create a local DateTime

public static

max(dateTimes: ...DateTime): DateTime

Return the max of several date times

public static

min(dateTimes: ...DateTime): DateTime

Return the min of several date times

public static

utc(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime

Create a DateTime in UTC

Member Summary

Public Members
public get

Get the day of the month (1-30ish).

public get

Returns the number of days in this DateTime's month

public get

Returns the number of days in this DateTime's year

public get

Get the hour of the day (0-23).

public get

Returns an explanation of why this DateTime became invalid, or null if the DateTime is valid

public get

Get whether the DateTime is in a DST.

public get

Returns true if this DateTime is in a leap year, false otherwise

public get

Get whether this zone's offset ever changes, as in a DST.

public get

Returns whether the DateTime is valid.

public get

Get the locale of a DateTime, such 'en-GB'.

public get

Get the millisecond of the second (0-999).

public get

Get the minute of the hour (0-59).

public get

Get the month (1-12).

public get

Get the human readable long month name, such as 'October'.

public get

Get the human readable short month name, such as 'Oct'.

public get

Get the numbering system of a DateTime, such 'beng'.

public get

Get the UTC offset of this DateTime in minutes

public get

Get the long human name for the zone's current offset, for example "Eastern Standard Time" or "Eastern Daylight Time". Defaults to the system's locale if no locale has been specified

public get

Get the short human name for the zone's current offset, for example "EST" or "EDT". Defaults to the system's locale if no locale has been specified

public get

Get the ordinal (i.e.

public get

Get the output calendar of a DateTime, such 'islamic'.

public get

Get the quarter

public get

Get the second of the minute (0-59).

public get

Get the week number of the week year (1-52ish).

public get

Get the week year

public get

Get the day of the week.

public get

Get the human readable long weekday, such as 'Monday'.

public get

Get the human readable short weekday, such as 'Mon'.

public get

Returns the number of weeks in this DateTime's year

public get

Get the year

public get

Get the name of the time zone.

Method Summary

Public Methods
public

Returns a string representation of this DateTime appropriate for the REPL.

public

diff(otherDateTime: DateTime, unit: string | string[], opts: Object): Duration

Return the difference between two DateTimes as a Duration.

public

diffNow(unit: string | string[], opts: Object): Duration

Return the difference between this DateTime and right now.

public

"Set" this DateTime to the end (i.e.

public

Equality check Two DateTimes are equal iff they represent the same millisecond, have the same zone and location, and are both valid.

public

get(unit: string): number

Get the value of unit.

public

hasSame(otherDateTime: DateTime, unit: string): boolean

Return whether this DateTime is in the same unit of time as another DateTime

public

minus(duration: Duration | Object | number): DateTime

Subtract a period of time to this DateTime and return the resulting DateTime See plus

public

plus(duration: Duration | Object | number): DateTime

Add a period of time to this DateTime and return the resulting DateTime

public

reconfigure(properties: Object): DateTime

"Set" the locale, numberingSystem, or outputCalendar.

public

Returns the resolved Intl options for this DateTime.

public

set(values: Object): DateTime

"Set" the values of specified units.

public

setLocale(locale: *): DateTime

"Set" the locale.

public

setZone(zone: string | Zone, opts: Object): DateTime

"Set" the DateTime's zone to specified zone. Returns a newly-constructed DateTime.

By default, the setter keeps the underlying time the same (as in, the same UTC timestamp), but the new instance will report different local times and consider DSTs when making computations, as with plus. You may wish to use toLocal and toUTC which provide simple convenience wrappers for commonly used zones.

public

"Set" this DateTime to the beginning of a unit of time.

public

Returns a BSON serializable equivalent to this DateTime.

public

toFormat(fmt: string, opts: Object): string

Returns a string representation of this DateTime formatted according to the specified format string.

public

Returns a string representation of this DateTime appropriate for use in HTTP headers.

public

toISO(opts: Object): string

Returns an ISO 8601-compliant string representation of this DateTime

public

Returns an ISO 8601-compliant string representation of this DateTime's date component

public

Returns an ISO 8601-compliant string representation of this DateTime's time component

public

Returns an ISO 8601-compliant string representation of this DateTime's week date

public

Returns a Javascript Date equivalent to this DateTime.

public

Returns an ISO 8601 representation of this DateTime appropriate for use in JSON.

public

"Set" the DateTime's zone to the host's local zone.

public

toLocaleParts(opts: *): *

Returns an array of format "parts", i.e.

public

Returns a localized string representing this date.

public

Returns the epoch milliseconds of this DateTime.

public

toObject(opts: *): Object

Returns a Javascript object with this DateTime's year, month, day, and so on.

public

Returns an RFC 2822-compatible string representation of this DateTime, always in UTC

public

toSQL(opts: Object): string

Returns a string representation of this DateTime appropriate for use in SQL DateTime

public

Returns a string representation of this DateTime appropriate for use in SQL Date

public

Returns a string representation of this DateTime appropriate for use in SQL Time

public

Returns a string representation of this DateTime appropriate for debugging

public

toUTC(offset: number, opts: Object): DateTime

"Set" the DateTime's zone to UTC. Returns a newly-constructed DateTime.

Equivalent to setZone('utc')

public

until(otherDateTime: DateTime): Interval

Return an Interval spanning between this DateTime and another DateTime

public

Returns the epoch milliseconds of this DateTime.

Static Public Members

public static get DATETIME_FULL: Object source

toLocaleString format like 'October 14, 1983, 9:30 AM EDT'. Only 12-hour if the locale is.

public static get DATETIME_FULL_WITH_SECONDS: Object source

toLocaleString format like 'October 14, 1983, 9:30:33 AM EDT'. Only 12-hour if the locale is.

public static get DATETIME_HUGE: Object source

toLocaleString format like 'Friday, October 14, 1983, 9:30 AM Eastern Daylight Time'. Only 12-hour if the locale is.

public static get DATETIME_HUGE_WITH_SECONDS: Object source

toLocaleString format like 'Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time'. Only 12-hour if the locale is.

public static get DATETIME_MED: Object source

toLocaleString format like 'Oct 14, 1983, 9:30 AM'. Only 12-hour if the locale is.

public static get DATETIME_MED_WITH_SECONDS: Object source

toLocaleString format like 'Oct 14, 1983, 9:30:33 AM'. Only 12-hour if the locale is.

public static get DATETIME_SHORT: Object source

toLocaleString format like '10/14/1983, 9:30 AM'. Only 12-hour if the locale is.

public static get DATETIME_SHORT_WITH_SECONDS: Object source

toLocaleString format like '10/14/1983, 9:30:33 AM'. Only 12-hour if the locale is.

public static get DATE_FULL: Object source

toLocaleString format like 'October 14, 1983'

public static get DATE_HUGE: Object source

toLocaleString format like 'Tuesday, October 14, 1983'

public static get DATE_MED: Object source

toLocaleString format like 'Oct 14, 1983'

public static get DATE_SHORT: Object source

toLocaleString format like 10/14/1983

public static get TIME_24_SIMPLE: Object source

toLocaleString format like '09:30', always 24-hour.

public static get TIME_24_WITH_LONG_OFFSET: Object source

toLocaleString format like '09:30:23 Eastern Daylight Time', always 24-hour.

public static get TIME_24_WITH_SECONDS: Object source

toLocaleString format like '09:30:23', always 24-hour.

public static get TIME_24_WITH_SHORT_OFFSET: Object source

toLocaleString format like '09:30:23 EDT', always 24-hour.

public static get TIME_SIMPLE: Object source

toLocaleString format like '09:30 AM'. Only 12-hour if the locale is.

public static get TIME_WITH_LONG_OFFSET: Object source

toLocaleString format like '09:30:23 AM Eastern Daylight Time'. Only 12-hour if the locale is.

public static get TIME_WITH_SECONDS: Object source

toLocaleString format like '09:30:23 AM'. Only 12-hour if the locale is.

public static get TIME_WITH_SHORT_OFFSET: Object source

toLocaleString format like '09:30:23 AM EDT'. Only 12-hour if the locale is.

Static Public Methods

public static fromFormat(text: string, fmt: string, options: Object): DateTime source

Create a DateTime from an input string and format string Defaults to en-US if no locale has been specified, regardless of the system's locale

Params:

NameTypeAttributeDescription
text string

the string to parse

fmt string

the format the string is expected to be in (see description)

options Object

options to affect the creation

options.zone string | Zone
  • optional
  • default: 'local'

use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone

options.setZone boolean
  • optional
  • default: false

override the zone with a zone specified in the string itself, if it specifies one

options.locale string
  • optional
  • default: 'en-US'

a locale string to use when parsing. Will also set the DateTime to this locale

options.numberingSystem string

the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

Return:

DateTime

public static fromFormatExplain(text: string, fmt: string, options: Object): Object source

Explain how a string would be parsed by fromFormat()

Params:

NameTypeAttributeDescription
text string

the string to parse

fmt string

the format the string is expected to be in (see description)

options Object

options taken by fromFormat()

Return:

Object

public static fromHTTP(text: string, options: Object): DateTime source

Create a DateTime from an HTTP header date

Params:

NameTypeAttributeDescription
text string

the HTTP header date

options Object

options to affect the creation

options.zone string | Zone
  • optional
  • default: 'local'

convert the time to this zone. Since HTTP dates are always in UTC, this has no effect on the interpretation of string, merely the zone the resulting DateTime is expressed in.

options.setZone boolean
  • optional
  • default: false

override the zone with the fixed-offset zone specified in the string. For HTTP dates, this is always UTC, so this option is equivalent to setting the zone option to 'utc', but this option is included for consistency with similar methods.

options.locale string
  • optional
  • default: 'en-US'

a locale to set on the resulting DateTime instance

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

options.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromHTTP('Sun, 06 Nov 1994 08:49:37 GMT')
DateTime.fromHTTP('Sunday, 06-Nov-94 08:49:37 GMT')
DateTime.fromHTTP('Sun Nov  6 08:49:37 1994')

See:

public static fromISO(text: string, opts: Object): DateTime source

Create a DateTime from an ISO 8601 string

Params:

NameTypeAttributeDescription
text string

the ISO string

opts Object

options to affect the creation

opts.zone string | Zone
  • optional
  • default: 'local'

use this zone if no offset is specified in the input string itself. Will also convert the time to this zone

opts.setZone boolean
  • optional
  • default: false

override the zone with a fixed-offset zone specified in the string itself, if it specifies one

opts.locale string
  • optional
  • default: 'en-US'

a locale to set on the resulting DateTime instance

opts.outputCalendar string

the output calendar to set on the resulting DateTime instance

opts.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromISO('2016-05-25T09:08:34.123')
DateTime.fromISO('2016-05-25T09:08:34.123+06:00')
DateTime.fromISO('2016-05-25T09:08:34.123+06:00', {setZone: true})
DateTime.fromISO('2016-05-25T09:08:34.123', {zone: 'utc'})
DateTime.fromISO('2016-W05-4')

public static fromJSDate(date: Date, options: Object): DateTime source

Create a DateTime from a Javascript Date object. Uses the default zone.

Params:

NameTypeAttributeDescription
date Date

a Javascript Date object

options Object

configuration options for the DateTime

options.zone string | Zone
  • optional
  • default: 'local'

the zone to place the DateTime into

Return:

DateTime

public static fromMillis(milliseconds: number, options: Object): DateTime source

Create a DateTime from a number of milliseconds since the epoch (i.e. since 1 January 1970 00:00:00 UTC). Uses the default zone.

Params:

NameTypeAttributeDescription
milliseconds number

a number of milliseconds since 1970 UTC

options Object

configuration options for the DateTime

options.zone string | Zone
  • optional
  • default: 'local'

the zone to place the DateTime into

options.locale string
  • optional

a locale to set on the resulting DateTime instance

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

options.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

public static fromObject(obj: Object): DateTime source

Create a DateTime from a Javascript object with keys like 'year' and 'hour' with reasonable defaults.

Params:

NameTypeAttributeDescription
obj Object

the object to create the DateTime from

obj.year number

a year, such as 1987

obj.month number

a month, 1-12

obj.day number

a day of the month, 1-31, depending on the month

obj.ordinal number

day of the year, 1-365 or 366

obj.weekYear number

an ISO week year

obj.weekNumber number

an ISO week number, between 1 and 52 or 53, depending on the year

obj.weekday number

an ISO weekday, 1-7, where 1 is Monday and 7 is Sunday

obj.hour number

hour of the day, 0-23

obj.minute number

minute of the hour, 0-59

obj.second number

second of the minute, 0-59

obj.millisecond number

millisecond of the second, 0-999

obj.zone string | Zone
  • optional
  • default: 'local'

interpret the numbers in the context of a particular zone. Can take any value taken as the first argument to setZone()

obj.locale string
  • optional
  • default: 'en-US'

a locale to set on the resulting DateTime instance

obj.outputCalendar string

the output calendar to set on the resulting DateTime instance

obj.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromObject({ year: 1982, month: 5, day: 25}).toISODate() //=> '1982-05-25'
DateTime.fromObject({ year: 1982 }).toISODate() //=> '1982-01-01T00'
DateTime.fromObject({ hour: 10, minute: 26, second: 6 }) //~> today at 10:26:06
DateTime.fromObject({ hour: 10, minute: 26, second: 6, zone: 'utc' }),
DateTime.fromObject({ hour: 10, minute: 26, second: 6, zone: 'local' })
DateTime.fromObject({ hour: 10, minute: 26, second: 6, zone: 'America/New_York' })
DateTime.fromObject({ weekYear: 2016, weekNumber: 2, weekday: 3 }).toISODate() //=> '2016-01-13'

public static fromRFC2822(text: string, opts: Object): DateTime source

Create a DateTime from an RFC 2822 string

Params:

NameTypeAttributeDescription
text string

the RFC 2822 string

opts Object

options to affect the creation

opts.zone string | Zone
  • optional
  • default: 'local'

convert the time to this zone. Since the offset is always specified in the string itself, this has no effect on the interpretation of string, merely the zone the resulting DateTime is expressed in.

opts.setZone boolean
  • optional
  • default: false

override the zone with a fixed-offset zone specified in the string itself, if it specifies one

opts.locale string
  • optional
  • default: 'en-US'

a locale to set on the resulting DateTime instance

opts.outputCalendar string

the output calendar to set on the resulting DateTime instance

opts.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromRFC2822('25 Nov 2016 13:23:12 GMT')
DateTime.fromRFC2822('Tue, 25 Nov 2016 13:23:12 +0600')
DateTime.fromRFC2822('25 Nov 2016 13:23 Z')

public static fromSQL(text: string, options: Object): DateTime source

Create a DateTime from a SQL date, time, or datetime Defaults to en-US if no locale has been specified, regardless of the system's locale

Params:

NameTypeAttributeDescription
text string

the string to parse

options Object

options to affect the creation

options.zone string | Zone
  • optional
  • default: 'local'

use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone

options.setZone boolean
  • optional
  • default: false

override the zone with a zone specified in the string itself, if it specifies one

options.locale string
  • optional
  • default: 'en-US'

a locale string to use when parsing. Will also set the DateTime to this locale

options.numberingSystem string

the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromSQL('2017-05-15')
DateTime.fromSQL('2017-05-15 09:12:34')
DateTime.fromSQL('2017-05-15 09:12:34.342')
DateTime.fromSQL('2017-05-15 09:12:34.342+06:00')
DateTime.fromSQL('2017-05-15 09:12:34.342 America/Los_Angeles')
DateTime.fromSQL('2017-05-15 09:12:34.342 America/Los_Angeles', { setZone: true })
DateTime.fromSQL('2017-05-15 09:12:34.342', { zone: 'America/Los_Angeles' })
DateTime.fromSQL('09:12:34.342')

public static fromString(text: *, fmt: *, opts: {}): * source

this method was deprecated. use fromFormat instead

Params:

NameTypeAttributeDescription
text *
fmt *
opts {}
  • optional
  • default: {}

Return:

*

public static fromStringExplain(text: *, fmt: *, options: {}): * source

this method was deprecated. use fromFormatExplain instead

Params:

NameTypeAttributeDescription
text *
fmt *
options {}
  • optional
  • default: {}

Return:

*

public static invalid(reason: *): DateTime source

Create an invalid DateTime.

Params:

NameTypeAttributeDescription
reason *

Return:

DateTime

public static local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime source

Create a local DateTime

Params:

NameTypeAttributeDescription
year number

The calendar year. If omitted (as in, call local() with no arguments), the current time will be used

month number
  • optional
  • default: 1

The month, 1-indexed

day number
  • optional
  • default: 1

The day of the month

hour number
  • optional
  • default: 0

The hour of the day, in 24-hour time

minute number
  • optional
  • default: 0

The minute of the hour, i.e. a number between 0 and 59

second number
  • optional
  • default: 0

The second of the minute, i.e. a number between 0 and 59

millisecond number
  • optional
  • default: 0

The millisecond of the second, i.e. a number between 0 and 999

Return:

DateTime

Example:

DateTime.local()                            //~> now
DateTime.local(2017)                        //~> 2017-01-01T00:00:00
DateTime.local(2017, 3)                     //~> 2017-03-01T00:00:00
DateTime.local(2017, 3, 12)                 //~> 2017-03-12T00:00:00
DateTime.local(2017, 3, 12, 5)              //~> 2017-03-12T05:00:00
DateTime.local(2017, 3, 12, 5, 45)          //~> 2017-03-12T05:45:00
DateTime.local(2017, 3, 12, 5, 45, 10)      //~> 2017-03-12T05:45:10
DateTime.local(2017, 3, 12, 5, 45, 10, 765) //~> 2017-03-12T05:45:10.765

public static max(dateTimes: ...DateTime): DateTime source

Return the max of several date times

Params:

NameTypeAttributeDescription
dateTimes ...DateTime

the DateTimes from which to choose the maximum

Return:

DateTime

the max DateTime, or undefined if called with no argument

public static min(dateTimes: ...DateTime): DateTime source

Return the min of several date times

Params:

NameTypeAttributeDescription
dateTimes ...DateTime

the DateTimes from which to choose the minimum

Return:

DateTime

the min DateTime, or undefined if called with no argument

public static utc(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime source

Create a DateTime in UTC

Params:

NameTypeAttributeDescription
year number

The calendar year. If omitted (as in, call utc() with no arguments), the current time will be used

month number
  • optional
  • default: 1

The month, 1-indexed

day number
  • optional
  • default: 1

The day of the month

hour number
  • optional
  • default: 0

The hour of the day, in 24-hour time

minute number
  • optional
  • default: 0

The minute of the hour, i.e. a number between 0 and 59

second number
  • optional
  • default: 0

The second of the minute, i.e. a number between 0 and 59

millisecond number
  • optional
  • default: 0

The millisecond of the second, i.e. a number between 0 and 999

Return:

DateTime

Example:

DateTime.utc()                            //~> now
DateTime.utc(2017)                        //~> 2017-01-01T00:00:00Z
DateTime.utc(2017, 3)                     //~> 2017-03-01T00:00:00Z
DateTime.utc(2017, 3, 12)                 //~> 2017-03-12T00:00:00Z
DateTime.utc(2017, 3, 12, 5)              //~> 2017-03-12T05:00:00Z
DateTime.utc(2017, 3, 12, 5, 45)          //~> 2017-03-12T05:45:00Z
DateTime.utc(2017, 3, 12, 5, 45, 10)      //~> 2017-03-12T05:45:10Z
DateTime.utc(2017, 3, 12, 5, 45, 10, 765) //~> 2017-03-12T05:45:10.765Z

Public Members

public get day: number source

Get the day of the month (1-30ish).

Example:

DateTime.local(2017, 5, 25).day //=> 25

public get daysInMonth: number source

Returns the number of days in this DateTime's month

Example:

DateTime.local(2016, 2).daysInMonth //=> 29
DateTime.local(2016, 3).daysInMonth //=> 31

public get daysInYear: number source

Returns the number of days in this DateTime's year

Example:

DateTime.local(2016).daysInYear //=> 366
DateTime.local(2013).daysInYear //=> 365

public get hour: number source

Get the hour of the day (0-23).

Example:

DateTime.local(2017, 5, 25, 9).hour //=> 9

public get invalidReason: string source

Returns an explanation of why this DateTime became invalid, or null if the DateTime is valid

public get isInDST: boolean source

Get whether the DateTime is in a DST.

public get isInLeapYear: boolean source

Returns true if this DateTime is in a leap year, false otherwise

Example:

DateTime.local(2016).isInLeapYear //=> true
DateTime.local(2013).isInLeapYear //=> false

public get isOffsetFixed: boolean source

Get whether this zone's offset ever changes, as in a DST.

public get isValid: boolean source

Returns whether the DateTime is valid. Invalid DateTimes occur when:

  • The DateTime was created from invalid calendar information, such as the 13th month or February 30
  • The DateTime was created by an operation on another invalid date

public get locale: string source

Get the locale of a DateTime, such 'en-GB'. The locale is used when formatting the DateTime

public get millisecond: number source

Get the millisecond of the second (0-999).

Example:

DateTime.local(2017, 5, 25, 9, 30, 52, 654).millisecond //=> 654

public get minute: number source

Get the minute of the hour (0-59).

Example:

DateTime.local(2017, 5, 25, 9, 30).minute //=> 30

public get month: number source

Get the month (1-12).

Example:

DateTime.local(2017, 5, 25).month //=> 5

public get monthLong: string source

Get the human readable long month name, such as 'October'. Defaults to the system's locale if no locale has been specified

Example:

DateTime.local(2017, 10, 30).monthLong //=> October

public get monthShort: string source

Get the human readable short month name, such as 'Oct'. Defaults to the system's locale if no locale has been specified

Example:

DateTime.local(2017, 10, 30).monthShort //=> Oct

public get numberingSystem: string source

Get the numbering system of a DateTime, such 'beng'. The numbering system is used when formatting the DateTime

public get offset: number source

Get the UTC offset of this DateTime in minutes

Example:

DateTime.local().offset //=> -240
DateTime.utc().offset //=> 0

public get offsetNameLong: string source

Get the long human name for the zone's current offset, for example "Eastern Standard Time" or "Eastern Daylight Time". Defaults to the system's locale if no locale has been specified

public get offsetNameShort: string source

Get the short human name for the zone's current offset, for example "EST" or "EDT". Defaults to the system's locale if no locale has been specified

public get ordinal: number | DateTime source

Get the ordinal (i.e. the day of the year)

Example:

DateTime.local(2017, 5, 25).ordinal //=> 145

public get outputCalendar: string source

Get the output calendar of a DateTime, such 'islamic'. The output calendar is used when formatting the DateTime

public get quarter: number source

Get the quarter

Example:

DateTime.local(2017, 5, 25).quarter //=> 2

public get second: number source

Get the second of the minute (0-59).

Example:

DateTime.local(2017, 5, 25, 9, 30, 52).second //=> 52

public get weekNumber: number source

Get the week number of the week year (1-52ish).

Example:

DateTime.local(2017, 5, 25).weekNumber //=> 21

See:

public get weekYear: number source

Get the week year

Example:

DateTime.local(2014, 11, 31).weekYear //=> 2015

See:

public get weekday: number source

Get the day of the week. 1 is Monday and 7 is Sunday

Example:

DateTime.local(2014, 11, 31).weekday //=> 4

See:

public get weekdayLong: string source

Get the human readable long weekday, such as 'Monday'. Defaults to the system's locale if no locale has been specified

Example:

DateTime.local(2017, 10, 30).weekdayLong //=> Monday

public get weekdayShort: string source

Get the human readable short weekday, such as 'Mon'. Defaults to the system's locale if no locale has been specified

Example:

DateTime.local(2017, 10, 30).weekdayShort //=> Mon

public get weeksInWeekYear: number source

Returns the number of weeks in this DateTime's year

Example:

DateTime.local(2004).weeksInWeekYear //=> 53
DateTime.local(2013).weeksInWeekYear //=> 52

See:

public get year: number source

Get the year

Example:

DateTime.local(2017, 5, 25).year //=> 2017

public get zoneName: string source

Get the name of the time zone.

Public Methods

public [customInspectSymbol](): string source

Returns a string representation of this DateTime appropriate for the REPL.

Return:

string

public diff(otherDateTime: DateTime, unit: string | string[], opts: Object): Duration source

Return the difference between two DateTimes as a Duration.

Params:

NameTypeAttributeDescription
otherDateTime DateTime

the DateTime to compare this one to

unit string | string[]
  • optional
  • default: ['milliseconds']

the unit or array of units (such as 'hours' or 'days') to include in the duration.

opts Object

options that affect the creation of the Duration

opts.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

Example:

var i1 = DateTime.fromISO('1982-05-25T09:45'),
    i2 = DateTime.fromISO('1983-10-14T10:30');
i2.diff(i1).toObject() //=> { milliseconds: 43807500000 }
i2.diff(i1, 'hours').toObject() //=> { hours: 12168.75 }
i2.diff(i1, ['months', 'days']).toObject() //=> { months: 16, days: 19.03125 }
i2.diff(i1, ['months', 'days', 'hours']).toObject() //=> { months: 16, days: 19, hours: 0.75 }

public diffNow(unit: string | string[], opts: Object): Duration source

Return the difference between this DateTime and right now. See diff

Params:

NameTypeAttributeDescription
unit string | string[]
  • optional
  • default: ['milliseconds']

the unit or units units (such as 'hours' or 'days') to include in the duration

opts Object

options that affect the creation of the Duration

opts.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

public endOf(unit: string): DateTime source

"Set" this DateTime to the end (i.e. the last millisecond) of a unit of time

Params:

NameTypeAttributeDescription
unit string

The unit to go to the end of. Can be 'year', 'month', 'day', 'hour', 'minute', 'second', or 'millisecond'.

Return:

DateTime

Example:

DateTime.local(2014, 3, 3).endOf('month').toISO(); //=> '2014-03-31T23:59:59.999-05:00'
DateTime.local(2014, 3, 3).endOf('year').toISO(); //=> '2014-12-31T23:59:59.999-05:00'
DateTime.local(2014, 3, 3, 5, 30).endOf('day').toISO(); //=> '2014-03-03T23:59:59.999-05:00'
DateTime.local(2014, 3, 3, 5, 30).endOf('hour').toISO(); //=> '2014-03-03T05:59:59.999-05:00'

public equals(other: DateTime): boolean source

Equality check Two DateTimes are equal iff they represent the same millisecond, have the same zone and location, and are both valid. To compare just the millisecond values, use +dt1 === ~dt2.

Params:

NameTypeAttributeDescription
other DateTime

the other DateTime

Return:

boolean

public get(unit: string): number source

Get the value of unit.

Params:

NameTypeAttributeDescription
unit string

a unit such as 'minute' or 'day'

Return:

number

Example:

DateTime.local(2017, 7, 4).get('month'); //=> 7
DateTime.local(2017, 7, 4).get('day'); //=> 4

public hasSame(otherDateTime: DateTime, unit: string): boolean source

Return whether this DateTime is in the same unit of time as another DateTime

Params:

NameTypeAttributeDescription
otherDateTime DateTime

the other DateTime

unit string

the unit of time to check sameness on

Return:

boolean

Example:

DateTime.local().hasSame(otherDT, 'day'); //~> true if both the same calendar day

public minus(duration: Duration | Object | number): DateTime source

Subtract a period of time to this DateTime and return the resulting DateTime See plus

Params:

NameTypeAttributeDescription
duration Duration | Object | number

The amount to subtract. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Return:

DateTime

public plus(duration: Duration | Object | number): DateTime source

Add a period of time to this DateTime and return the resulting DateTime

Adding hours, minutes, seconds, or milliseconds increases the timestamp by the right number of milliseconds. Adding days, months, or years shifts the calendar, accounting for DSTs and leap years along the way. Thus, dt.plus({ hours: 24 }) may result in a different time than dt.plus({ days: 1 }) if there's a DST shift in between.

Params:

NameTypeAttributeDescription
duration Duration | Object | number

The amount to add. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Return:

DateTime

Example:

DateTime.local().plus(123) //~> in 123 milliseconds
DateTime.local().plus({ minutes: 15 }) //~> in 15 minutes
DateTime.local().plus({ days: 1 }) //~> this time tomorrow
DateTime.local().plus({ days: -1 }) //~> this time yesterday
DateTime.local().plus({ hours: 3, minutes: 13 }) //~> in 1 hr, 13 min
DateTime.local().plus(Duration.fromObject({ hours: 3, minutes: 13 })) //~> in 1 hr, 13 min

public reconfigure(properties: Object): DateTime source

"Set" the locale, numberingSystem, or outputCalendar. Returns a newly-constructed DateTime.

Params:

NameTypeAttributeDescription
properties Object

the properties to set

Return:

DateTime

Example:

DateTime.local(2017, 5, 25).reconfigure({ locale: 'en-GB' })

public resolvedLocaleOpts(opts: Object): Object source

Returns the resolved Intl options for this DateTime. This is useful in understanding the behavior of formatting methods

Params:

NameTypeAttributeDescription
opts Object

the same options as toLocaleString

Return:

Object

public set(values: Object): DateTime source

"Set" the values of specified units. Returns a newly-constructed DateTime. You can only set units with this method; for "setting" metadata, see reconfigure and setZone.

Params:

NameTypeAttributeDescription
values Object

a mapping of units to numbers

Return:

DateTime

Example:

dt.set({ year: 2017 })
dt.set({ hour: 8, minute: 30 })
dt.set({ weekday: 5 })
dt.set({ year: 2005, ordinal: 234 })

public setLocale(locale: *): DateTime source

"Set" the locale. Returns a newly-constructed DateTime. Just a convenient alias for reconfigure({ locale })

Params:

NameTypeAttributeDescription
locale *

Return:

DateTime

Example:

DateTime.local(2017, 5, 25).setLocale('en-GB')

public setZone(zone: string | Zone, opts: Object): DateTime source

"Set" the DateTime's zone to specified zone. Returns a newly-constructed DateTime.

By default, the setter keeps the underlying time the same (as in, the same UTC timestamp), but the new instance will report different local times and consider DSTs when making computations, as with plus. You may wish to use toLocal and toUTC which provide simple convenience wrappers for commonly used zones.

Params:

NameTypeAttributeDescription
zone string | Zone
  • optional
  • default: 'local'

a zone identifier. As a string, that can be any IANA zone supported by the host environment, or a fixed-offset name of the form 'utc+3', or the strings 'local' or 'utc'. You may also supply an instance of a Zone class.

opts Object

options

opts.keepLocalTime boolean
  • optional
  • default: false

If true, adjust the underlying time so that the local time stays the same, but in the target zone. You should rarely need this.

Return:

DateTime

public startOf(unit: string): DateTime source

"Set" this DateTime to the beginning of a unit of time.

Params:

NameTypeAttributeDescription
unit string

The unit to go to the beginning of. Can be 'year', 'month', 'day', 'hour', 'minute', 'second', or 'millisecond'.

Return:

DateTime

Example:

DateTime.local(2014, 3, 3).startOf('month').toISODate(); //=> '2014-03-01'
DateTime.local(2014, 3, 3).startOf('year').toISODate(); //=> '2014-01-01'
DateTime.local(2014, 3, 3, 5, 30).startOf('day').toISOTime(); //=> '00:00.000-05:00'
DateTime.local(2014, 3, 3, 5, 30).startOf('hour').toISOTime(); //=> '05:00:00.000-05:00'

public toBSON(): Date source

Returns a BSON serializable equivalent to this DateTime.

Return:

Date

public toFormat(fmt: string, opts: Object): string source

Returns a string representation of this DateTime formatted according to the specified format string. You may not want this. See toLocaleString for a more flexible formatting tool. For a table of tokens and their interpretations, see here. Defaults to en-US if no locale has been specified, regardless of the system's locale.

Params:

NameTypeAttributeDescription
fmt string

the format string

opts Object

options

opts.round boolean

round numerical values

Return:

string

Example:

DateTime.local().toFormat('yyyy LLL dd') //=> '2017 Apr 22'
DateTime.local().setLocale('fr').toFormat('yyyy LLL dd') //=> '2017 avr. 22'
DateTime.local().toFormat("HH 'hours and' mm 'minutes'") //=> '20 hours and 55 minutes'

See:

public toHTTP(): string source

Returns a string representation of this DateTime appropriate for use in HTTP headers. Specifically, the string conforms to RFC 1123.

Return:

string

Example:

DateTime.utc(2014, 7, 13).toHTTP() //=> 'Sun, 13 Jul 2014 00:00:00 GMT'
DateTime.utc(2014, 7, 13, 19).toHTTP() //=> 'Sun, 13 Jul 2014 19:00:00 GMT'

See:

public toISO(opts: Object): string source

Returns an ISO 8601-compliant string representation of this DateTime

Params:

NameTypeAttributeDescription
opts Object

options

opts.suppressMilliseconds boolean
  • optional
  • default: false

exclude milliseconds from the format if they're 0

opts.suppressSeconds boolean
  • optional
  • default: false

exclude seconds from the format if they're 0

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc(1982, 5, 25).toISO() //=> '1982-05-25T00:00:00.000Z'
DateTime.local().toISO() //=> '2017-04-22T20:47:05.335-04:00'
DateTime.local().toISO({ includeOffset: false }) //=> '2017-04-22T20:47:05.335'

public toISODate(): string source

Returns an ISO 8601-compliant string representation of this DateTime's date component

Return:

string

Example:

DateTime.utc(1982, 5, 25).toISODate() //=> '1982-05-25'

public toISOTime(opts: Object): string source

Returns an ISO 8601-compliant string representation of this DateTime's time component

Params:

NameTypeAttributeDescription
opts Object

options

opts.suppressMilliseconds boolean
  • optional
  • default: false

exclude milliseconds from the format if they're 0

opts.suppressSeconds boolean
  • optional
  • default: false

exclude seconds from the format if they're 0

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc().hour(7).minute(34).toISOTime() //=> '07:34:19.361Z'
DateTime.utc().hour(7).minute(34).toISOTime({ suppressSeconds: true }) //=> '07:34Z'

public toISOWeekDate(): string source

Returns an ISO 8601-compliant string representation of this DateTime's week date

Return:

string

Example:

DateTime.utc(1982, 5, 25).toISOWeekDate() //=> '1982-W21-2'

public toJSDate(): Date source

Returns a Javascript Date equivalent to this DateTime.

Return:

Date

public toJSON(): string source

Returns an ISO 8601 representation of this DateTime appropriate for use in JSON.

Return:

string

public toLocal(): DateTime source

"Set" the DateTime's zone to the host's local zone. Returns a newly-constructed DateTime.

Equivalent to setZone('local')

Return:

DateTime

public toLocaleParts(opts: *): * source

Returns an array of format "parts", i.e. individual tokens along with metadata. This is allows callers to post-process individual sections of the formatted output. Defaults to the system's locale if no locale has been specified

Params:

NameTypeAttributeDescription
opts *

{Object} - Intl.DateTimeFormat constructor options, same as toLocaleString.

Return:

*

Example:

DateTime.local().toLocaleString(); //=> [
                                   //=>   { type: 'day', value: '25' },
                                   //=>   { type: 'literal', value: '/' },
                                   //=>   { type: 'month', value: '05' },
                                   //=>   { type: 'literal', value: '/' },
                                   //=>   { type: 'year', value: '1982' }
                                   //=> ]

See:

public toLocaleString(opts: *): string source

Returns a localized string representing this date. Accepts the same options as the Intl.DateTimeFormat constructor and any presets defined by Luxon, such as DateTime.DATE_FULL or DateTime.TIME_SIMPLE. The exact behavior of this method is browser-specific, but in general it will return an appropriate representation. of the DateTime in the assigned locale. Defaults to the system's locale if no locale has been specified

Params:

NameTypeAttributeDescription
opts *

{Object} - Intl.DateTimeFormat constructor options

Return:

string

Example:

DateTime.local().toLocaleString(); //=> 4/20/2017
DateTime.local().setLocale('en-gb').toLocaleString(); //=> '20/04/2017'
DateTime.local().toLocaleString(DateTime.DATE_FULL); //=> 'April 20, 2017'
DateTime.local().toLocaleString(DateTime.TIME_SIMPLE); //=> '11:32 AM'
DateTime.local().toLocaleString(DateTime.DATETIME_SHORT); //=> '4/20/2017, 11:32 AM'
DateTime.local().toLocaleString({weekday: 'long', month: 'long', day: '2-digit'}); //=> 'Thu, Apr 20'
DateTime.local().toLocaleString({weekday: 'long', month: 'long', day: '2-digit', hour: '2-digit', minute: '2-digit'}); //=> 'Thu, Apr 20, 11:27'
DateTime.local().toLocaleString({hour: '2-digit', minute: '2-digit'}); //=> '11:32'

See:

public toMillis(): number source

Returns the epoch milliseconds of this DateTime.

Return:

number

public toObject(opts: *): Object source

Returns a Javascript object with this DateTime's year, month, day, and so on.

Params:

NameTypeAttributeDescription
opts *

options for generating the object

opts.includeConfig boolean
  • optional
  • default: false

include configuration attributes in the output

Return:

Object

Example:

DateTime.local().toObject() //=> { year: 2017, month: 4, day: 22, hour: 20, minute: 49, second: 42, millisecond: 268 }

public toRFC2822(): string source

Returns an RFC 2822-compatible string representation of this DateTime, always in UTC

Return:

string

Example:

DateTime.utc(2014, 7, 13).toRFC2822() //=> 'Sun, 13 Jul 2014 00:00:00 +0000'
DateTime.local(2014, 7, 13).toRFC2822() //=> 'Sun, 13 Jul 2014 00:00:00 -0400'

public toSQL(opts: Object): string source

Returns a string representation of this DateTime appropriate for use in SQL DateTime

Params:

NameTypeAttributeDescription
opts Object

options

opts.includeZone boolean
  • optional
  • default: false

include the zone, such as 'America/New_York'. Overrides includeOffset.

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc(2014, 7, 13).toSQL() //=> '2014-07-13 00:00:00.000 Z'
DateTime.local(2014, 7, 13).toSQL() //=> '2014-07-13 00:00:00.000 -04:00'
DateTime.local(2014, 7, 13).toSQL({ includeOffset: false }) //=> '2014-07-13 00:00:00.000'
DateTime.local(2014, 7, 13).toSQL({ includeZone: false }) //=> '2014-07-13 00:00:00.000 America/New_York'

public toSQLDate(): string source

Returns a string representation of this DateTime appropriate for use in SQL Date

Return:

string

Example:

DateTime.utc(2014, 7, 13).toSQLDate() //=> '2014-07-13'

public toSQLTime(opts: Object): string source

Returns a string representation of this DateTime appropriate for use in SQL Time

Params:

NameTypeAttributeDescription
opts Object

options

opts.includeZone boolean
  • optional
  • default: false

include the zone, such as 'America/New_York'. Overides includeOffset.

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc().toSQL() //=> '05:15:16.345'
DateTime.local().toSQL() //=> '05:15:16.345 -04:00'
DateTime.local().toSQL({ includeOffset: false }) //=> '05:15:16.345'
DateTime.local().toSQL({ includeZone: false }) //=> '05:15:16.345 America/New_York'

public toString(): string source

Returns a string representation of this DateTime appropriate for debugging

Return:

string

public toUTC(offset: number, opts: Object): DateTime source

"Set" the DateTime's zone to UTC. Returns a newly-constructed DateTime.

Equivalent to setZone('utc')

Params:

NameTypeAttributeDescription
offset number
  • optional
  • default: 0

optionally, an offset from UTC in minutes

opts Object
  • optional
  • default: {}

options to pass to setZone()

Return:

DateTime

public until(otherDateTime: DateTime): Interval source

Return an Interval spanning between this DateTime and another DateTime

Params:

NameTypeAttributeDescription
otherDateTime DateTime

the other end point of the Interval

Return:

Interval

public valueOf(): number source

Returns the epoch milliseconds of this DateTime. Alias of toMillis

Return:

number