--- title: Date Utils --- Quasar provides a set of useful functions to manipulate JS Date easily in most use cases, without the high additional cost of integrating dedicated libraries like Momentjs. Most Quasar date functions take as parameter either a Unix timestamp or a String representing a date which needs to be parsable by the native JS [Date constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date). Some examples: `1497159857411`, `Sun Jun 11 2017 08:44:42 GMT+0300`, `2017-06-16`. Returned values are all JS Dates. Get familiar with JS native Date class, which is very powerful, and remember that you don't need solutions like Momentjs which add hundreds of minified KB to your bundle. > [!NOTE] > Quasar date utils includes tree shaking, except for the UMD version. You will notice all examples import `date` Object from Quasar. However, if you need only one method from it, then you can use destructuring to help Tree Shaking embed only that method and not all of `date`. Example with `addToDate()`: ```js // we import all of `date` import { date } from 'quasar' // destructuring to keep only what is needed const { addToDate } = date const newDate = addToDate(new Date(), { days: 7, months: 1 }) ``` > [!NOTE] > For usage with the UMD build see [here](../start/umd.md#quasar-global-object). ## Format for display It takes a string of tokens and replaces them with their corresponding date values: ```js import { date } from 'quasar' const timeStamp = Date.now() const formattedString = date.formatDate(timeStamp, 'YYYY-MM-DDTHH:mm:ss.SSSZ') ``` For i18n, you can use a third parameter: ```js const formattedString = date.formatDate(timeStamp, 'MMMM - dddd', { days: [ 'Duminica', 'Luni' /* and all the rest of days - remember starting with Sunday */ ], daysShort: [ 'Dum', 'Lun' /* and all the rest of days - remember starting with Sunday */ ], months: ['Ianuarie', 'Februarie' /* and all the rest of months */], monthsShort: ['Ian', 'Feb' /* and all the rest of months */] }) ``` Available format tokens: | Unit | Formats available | | --- | --- | | Year | | | Month | | | Quarter | | | Day of Month | | | Day of Year | | | Day of Week | | | Day of Week (ISO) | | | Week of Year | | | ISO Week Year | | | Hour | | | Minute | | | Second | | | Fractional Second | | | Timezone offset | | | AM/PM | | | Unix Timestamp | | If you want to insert strings (including `[` and `]` characters) into your mask, make sure you escape them by surrounding them with `[` and `]`, otherwise the characters might be interpreted as format tokens. ## Manipulate dates ### Create **Try to create dates with native JS Date class** like so: ```js const date = new Date() ``` The following method is just a wrapper to help you in cases where you just need current time but with a different year, or month, or second etc. ```js import { date } from 'quasar' const newDate = date.buildDate({ year: 2010, date: 5, hours: 15, milliseconds: 123 }) ``` You can pass a second argument (a boolean) for setting UTC time (true) instead of local time. The object literal provided can contain the following keys (all are optional): | Key | Description | | --- | --- | | `millisecond(s)` | for the milliseconds component of the date/time | | `second(s)` | for the seconds component of the date/time | | `minute(s)` | for the minutes component of the date/time | | `hour(s)` | for the hours component of the date/time | | `day(s)` / `date` | for the day component of the date/time | | `month(s)` | for the month component of the date/time | | `year(s)` | for the year component of the date/time | ### Validate To check if a date string is valid use: ```js import { date } from 'quasar' const dateString = 'Wed, 09 Aug 1995 00:00:00 GMT' if (date.isValid(dateString)) { // Do something with date string } ``` > [!WARNING] > `isValid` only validates the date format, not the logic validity of the date. > > The underlying implementation is based on native `Date.parse(...)` API and its shortcomings will pass through our API. > > It will not check if the date is valid for the month (e.g. 31st of February), or if the date is valid for the year (e.g. 29th of February in a non-leap year), and will return a different value in those cases for Firefox with respect to Chromium-based browsers (Chrome, Edge, etc). ### Add/Subtract To add/subtract some duration to/from a date use: ```js import { date } from 'quasar' let newDate = new Date(2017, 2, 7) newDate = date.addToDate(newDate, { days: 7, months: 1 }) // `newDate` is now 2017-3-14 00:00:00 newDate = date.subtractFromDate(newDate, { hours: 24, milliseconds: 10000 }) // `newDate` is now 2017-3-12 23:59:50 ``` The object literal provided can contain the following keys (all are optional): | Key | Description | | --- | --- | | `millisecond(s)` | for a duration in milliseconds | | `second(s)` | for a duration in seconds | | `minute(s)` | for a duration in minutes | | `hour(s)` | for a duration in hours | | `day(s)` / `date` | for a duration in days | | `month(s)` | for a duration in months | | `year(s)` | for a duration in years | ### Set date/time To set a specified unit(s) of date/time: ```js import { date } from 'quasar' const newDate = new Date(2017, 10, 2) const adjustedDate = date.adjustDate(newDate, { year: 2010, month: 2 }) // `adjustedDate` is 2010-2-2 ``` You can pass a third argument (a Boolean) for setting UTC time (`true`) instead of local time. The object literal provided can contain the following keys (all are optional): | Key | Description | | --- | --- | | `millisecond(s)` | for the milliseconds component of the date/time | | `second(s)` | for the seconds component of the date/time | | `minute(s)` | for the minutes component of the date/time | | `hour(s)` | for the hours component of the date/time | | `day(s)` / `date` | for the day component of the date/time | | `month(s)` | for the month component of the date/time | | `year(s)` | for the year component of the date/time | ## Query dates ### Minimum/Maximum To get the minimum/maximum date of a date set (i.e. array) use: ```js import { date } from 'quasar' let min = date.getMinDate( new Date(2017, 6, 24), new Date(2017, 5, 20), new Date(2017, 6, 26) ) // `min` is 2017-5-20 let max = date.getMaxDate( new Date(2017, 6, 24), new Date(2017, 5, 20), new Date(2017, 6, 26) ) // `max` is 2017-6-26 // Or use an array: const dates = [ new Date(2017, 6, 24), new Date(2017, 5, 20), new Date(2017, 6, 26) ] let min = date.getMinDate(...dates) // `min` is 2017-5-20 let max = date.getMaxDate(...dates) // `max` is 2017-6-26 ``` Note that the returning value is a timestamp. ```js console.log(max) // 1497906000000 console.log(new Date(max)) // Wed Jul 26 2017 00:00:00 GMT+0300 (Eastern European Summer Time) ``` ### Time range To check if a date is in a given date/time range use: ```js import { date } from 'quasar' const dateTarget = new Date() const dateFrom = new Date() const dateTo = new Date() // **strictly** (i.e. exclusive range) if (date.isBetweenDates(dateTarget, dateFrom, dateTo)) { // Do something with dateTarget } // including which margin you want if ( date.isBetweenDates(dateTarget, dateFrom, dateTo, { inclusiveFrom: true, inclusiveTo: true }) ) { // Do something with dateTarget } // if you only care about comparing dates (year/month/day, regardless of time) // then you could tip isBetweenDates() about it so it can perform best: if (date.isBetweenDates(dateTarget, dateFrom, dateTo, { onlyDate: true })) { // Do something with dateTarget } ``` To normalize a date in a given date/time range use: ```js import { date } from 'quasar' const newDate = new Date() const dateMin = new Date(2010, 2, 23) const dateMax = new Date(2012, 4, 12) const dateNormalized = date.getDateBetween(newDate, dateMin, dateMax) // Returns `newDate` if it's between 2010-2-23 and 2012-4-12; `dateMin` if it's lower; `dateMax` if it's greater ``` ### Equality To check if two dates' unit are **equal** use: ```js import { date } from 'quasar' const date1 = new Date(2017, 2, 5) const date2 = new Date(2017, 3, 8) const unit = 'year' if (date.isSameDate(date1, date2, /* optional */ unit)) { // true because date1 and date2's year is the same } ``` Unit parameter can be omitted, in which case a full date/time comparison will occur, otherwise it allows to perform partial comparison: | Unit | Description | | --- | --- | | `second(s)` | test if same second only | | `minute(s)` | test if same minute only | | `hour(s)` | test if same hour only | | `day(s)` / `date` | test if same day only | | `month(s)` | test if same month only | | `year(s)` | test if same year only | ### Difference To compute the difference between two dates use: ```js import { date } from 'quasar' const date1 = new Date(2017, 4, 12) const date2 = new Date(2017, 3, 8) const unit = 'days' const diff = date.getDateDiff(date1, date2, unit) // `diff` is 34 (days) ``` The unit parameter indicates the unit of measurement, if not specified then it is `days` by default: | Unit | Description | | --- | --- | | `second(s)` | distance in seconds (disregarding milliseconds) | | `minute(s)` | distance in minutes (disregarding seconds, ...) | | `hour(s)` | distance in hours (disregarding minutes, seconds, ...) | | `day(s)` / `date` | distance in calendar days | | `month(s)` | distance in calendar months | | `year(s)` | distance in calendar years | ### Calendar To get the [ISO week number in year](https://en.wikipedia.org/wiki/ISO_week_date) for a given date object use: ```js import { date } from 'quasar' const newDate = new Date(2017, 0, 4) const week = date.getWeekOfYear(newDate) // `week` is 1 ``` To get the [ISO week year](https://en.wikipedia.org/wiki/ISO_week_date) (the year that the ISO week belongs to, which can differ from the calendar year for dates around January 1st) for a given date object use: ```js import { date } from 'quasar' const newDate = new Date(2022, 0, 1) // in the last ISO week of 2021 const year = date.getISOWeekYear(newDate) // `year` is 2021 const week = date.getWeekOfYear(newDate) // `week` is 52 ``` Pair the `GGGG` format token with `ww` (never with `YYYY`) when formatting ISO week dates, e.g. `formatDate(newDate, 'GGGG-[W]ww')` outputs `2021-W52`. To get the day number in year for a given date object use: ```js import { date } from 'quasar' const newDate = new Date(2017, 1, 4) const day = date.getDayOfYear(newDate) // `day` is 35 ``` To get the day number in week for a given date object use: ```js import { date } from 'quasar' const newDate = new Date(2017, 1, 9) const day = date.getDayOfWeek(newDate) // `day` is 4 ``` #### Days in a month `date.daysInMonth(date, utc)` returns the number of days in the month containing the specified date without mutating the input. The optional `utc` Boolean defaults to `false`, which reads the input's local year and month. Set it to `true` to read the UTC year and month instead. This is useful when the input represents a UTC calendar value that could fall in a different month when converted to local time. ```js import { date } from 'quasar' const leapYearDate = new Date('2024-02-15T12:00:00.000Z') const localDays = date.daysInMonth(leapYearDate) // 29 const utcDays = date.daysInMonth(leapYearDate, true) // 29 ``` ### Start/End of time To mutate the original date object by setting it to the start of a unit of time use: ```js import { date } from 'quasar' let newDate = new Date('2000') // set to beginning of year 2000 (January 1st, 2000, 00:00:00.000) newDate = date.startOfDate(newDate, 'year') // set to end of year 2000 (December 31st, 2000, 23:59:59.999) newDate = date.endOfDate(newDate, 'year') ``` The second parameter indicates a unit to reset to (beginning of it or end of it): | Unit | Description | | --- | --- | | `second(s)` | reset seconds | | `minute(s)` | reset minutes | | `hour(s)` | reset hours | | `day(s)` / `date` | reset days | | `month(s)` | reset months | | `year(s)` | reset years | ## Other ### Get Format ```js import { date } from 'quasar' date.inferDateFormat(new Date()) // 'date' date.inferDateFormat(35346363) // 'number' date.inferDateFormat('Mon Feb 05 2018 23:05:29') // string ``` ### Cloning Date ```js import { date } from 'quasar' const newDate = new Date() const clonedDate = date.clone(newDate) date.addToDate(newDate, { days: 1 }) console.log(newDate.getDate() === clonedDate.getDate()) // false ``` ### Extract Date Using locale set by current Quasar language pack, this allows you to parse any string into a date object based on the format passed: ```js import { date } from 'quasar' // Example 1 const date = date.extractDate('2019-10-29 --- 23:12', 'YYYY-MM-DD --- HH:mm') // date is a new Date() object // Example 2 const date = date.extractDate('21/03/1985', 'DD/MM/YYYY') // date is a new Date() object ``` The input may contain additional text after the part described by the mask. When the input does not start with a matching value, or contains an impossible date, time, or timezone component, `extractDate()` returns an `Invalid Date`object: ```js const parsed = date.extractDate('2024-02-30', 'YYYY-MM-DD') console.log(Number.isNaN(parsed.getTime())) // true ``` ### Extracting ISO week dates *(v2.30+)* A mask that carries a week number (`w`, `wo` or `ww`) is resolved as an [ISO week date](https://en.wikipedia.org/wiki/ISO_week_date), so `formatDate()` output round-trips back into the same day: ```js import { date } from 'quasar' date.extractDate('2020-W40-7', 'GGGG-[W]ww-E') // Sunday, October 4th 2020 ``` The year comes from `GG`/`GGGG` when the mask has one, otherwise from `YY`/`YYYY`. Prefer the ISO week year tokens: for the days around January 1st the calendar year and the ISO week year differ, and pairing `YYYY` with `ww` then resolves to a day in the wrong week. The weekday comes from whichever of `E`, `d`, `do`, `dd`, `ddd` or `dddd` the mask carries. Masks without a weekday resolve to the Monday that starts the week, since ISO weeks start on Monday: ```js date.extractDate('2020-40', 'YYYY-ww') // Monday, September 28th 2020 ``` Weeks are always interpreted per ISO 8601 (weeks start on Monday, week 1 is the one holding January 4th), matching what `formatDate()` writes and what `getWeekOfYear()` returns. The language pack in use does not shift them, and neither does the `first-day-of-week` property of QDate, which only affects how a calendar is displayed. An impossible week is an `Invalid Date`, including week 53 of a year that only has 52 of them: ```js const parsed = date.extractDate('2021-W53', 'GGGG-[W]ww') console.log(Number.isNaN(parsed.getTime())) // true ``` When a mask carries both a week number and a full calendar date, the calendar date wins: ```js date.extractDate('2021-W52 2022-01-01', 'GGGG-[W]ww YYYY-MM-DD') // January 1st 2022 ``` > [!WARNING] > The `dd` token shortens a day name to its first two characters, which is not unique in every language (Chinese shortens all seven days to the same two characters). Where the current language pack is ambiguous that way, `dd` is matched but ignored, and the date resolves to the Monday of the week. Use `ddd`, `dddd` or `E` for a weekday that parses everywhere. With optional custom locale: Custom day and month names are matched literally, including any regular expression metacharacters they contain. ```js import { date } from 'quasar' const obj = date.extractDate( 'Month: Feb, Day: 11th, Year: 2018', '[Month: ]MMM[, Day: ]Do[, Year: ]YYYY', { days: [ 'Duminica', 'Luni' /* and all the rest of days - remember starting with Sunday */ ], daysShort: [ 'Dum', 'Lun' /* and all the rest of days - remember starting with Sunday */ ], months: ['Ianuarie', 'Februarie' /* and all the rest of months */], monthsShort: ['Ian', 'Feb' /* and all the rest of months */] } ) // obj is a new Date() object ```