Date

Module to generate dates.

Overview

To quickly generate a date in the past, use recent() (last day) or past() (last year). To quickly generate a date in the future, use soon() (next day) or future() (next year). For a realistic birthdate for an adult, use birthdate().

For more control, any of these methods can be customized with further options, or use between() to generate a single date between two dates, or betweens() for multiple dates.

Dates can be specified as Javascript Date objects, strings or UNIX timestamps. For example to generate a date between 1st January 2000 and now, use:

faker.date.between({ from: '2000-01-01', to: Date.now() });

You can generate random localized month and weekday names using month() and weekday().

These methods have additional concerns about reproducibility, see Reproducible Results.

anytime

Generates a random date that can be either in the past or in the future.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The optional options object.
options.refDate?	string | number | Date	faker.defaultRefDate()	The date to use as reference point for the newly generated date.

Returns: Date

function anytime(
    options: {
      refDate?: string | Date | number;
    } = {}
  ): Date;
faker.date.anytime() // '2022-07-31T01:33:29.567Z'

See Also

• faker.date.between(): For generating dates in a specific range.
• faker.date.past(): For generating dates explicitly in the past.
• faker.date.future(): For generating dates explicitly in the future.

Source

• View Source

between

Generates a random date between the given boundaries.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ ... }		The options object.
options.from	string | number | Date		The early date boundary.
options.to	string | number | Date		The late date boundary.

Returns: Date

Throws: If from or to are not provided. If from is after to.

function between(options: {
    from: string | Date | number;
    to: string | Date | number;
  }): Date;
faker.date.between({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' }) // '2026-05-16T02:22:53.002Z'

Source

• View Source

betweens

Generates random dates between the given boundaries. The dates will be returned in an array sorted in chronological order.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ ... }		The options object.
options.count?	number | { min: number; max: number; }	3	The number of dates to generate.
options.from	string | number | Date		The early date boundary.
options.to	string | number | Date		The late date boundary.

Returns: Date[]

Throws: If from or to are not provided. If from is after to.

function betweens(options: {
    from: string | Date | number;
    to: string | Date | number;
    count?:
      | number
      | {
          min: number;
          max: number;
        };
  }): Date[];
faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' })
// [
//   2022-07-02T06:00:00.000Z,
//   2024-12-31T12:00:00.000Z,
//   2027-07-02T18:00:00.000Z
// ]
faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: 2 })
// [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]
faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: { min: 2, max: 5 }})
// [
//   2021-12-19T06:35:40.191Z,
//   2022-09-10T08:03:51.351Z,
//   2023-04-19T11:41:17.501Z
// ]

Source

• View Source

birthdate

Returns a random birthdate. By default, the birthdate is generated for an adult between 18 and 80 years old. But you can customize the 'age' range or the 'year' range to generate a more specific birthdate.

Available since v7.0.0

Parameters

Name	Type	Default	Description
options?	{ ... } | { ... }	{}	The options to use to generate the birthdate.
options.refDate?	string | number | Date	faker.defaultRefDate()	The date to use as reference point for the newly generated date.
options.max	number		The maximum age/year to generate a birthdate for/in.
options.min	number		The minimum age/year to generate a birthdate for/in.
options.mode	'age' | 'year'		Either 'age' or 'year' to generate a birthdate based on the age or year range.
options.refDate?	string | number | Date	faker.defaultRefDate()	The date to use as reference point for the newly generated date. Only used when mode is 'age'.

Returns: Date

function birthdate(
    options?:
      | {
          refDate?: string | Date | number;
        }
      | {
          mode: 'age' | 'year';
          min: number;
          max: number;
          refDate?: string | Date | number;
        }
  ): Date;
faker.date.birthdate() // 1977-07-10T01:37:30.719Z
faker.date.birthdate({ mode: 'age', min: 18, max: 65 }) // 2003-11-02T20:03:20.116Z
faker.date.birthdate({ mode: 'year', min: 1900, max: 2000 }) // 1940-08-20T08:53:07.538Z

Source

• View Source

future

Generates a random date in the future.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The optional options object.
options.refDate?	string | number | Date	faker.defaultRefDate()	The date to use as reference point for the newly generated date.
options.years?	number	1	The range of years the date may be in the future.

Returns: Date

function future(
    options: {
      years?: number;
      refDate?: string | Date | number;
    } = {}
  ): Date;
faker.date.future() // '2022-11-19T05:52:49.100Z'
faker.date.future({ years: 10 }) // '2030-11-23T09:38:28.710Z'
faker.date.future({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-12-13T22:45:10.252Z'

See Also

• faker.date.soon(): For generating dates in the near future (days instead of years).

Source

• View Source

month

Returns a random name of a month.

Available since v3.0.1

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The optional options to use.
options.abbreviated?	boolean	false	Whether to return an abbreviation.
options.context?	boolean	false	Whether to return the name of a month in the context of a date. In the default en locale this has no effect, however, in other locales like fr or ru, this may affect grammar or capitalization, for example 'январь' with { context: false } and 'января' with { context: true } in ru.

Returns: string

function month(
    options: {
      abbreviated?: boolean;
      context?: boolean;
    } = {}
  ): string;
faker.date.month() // 'October'
faker.date.month({ abbreviated: true }) // 'Feb'
faker.date.month({ context: true }) // 'June'
faker.date.month({ abbreviated: true, context: true }) // 'Sep'

Source

• View Source

past

Generates a random date in the past.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The optional options object.
options.refDate?	string | number | Date	faker.defaultRefDate()	The date to use as reference point for the newly generated date.
options.years?	number	1	The range of years the date may be in the past.

Returns: Date

function past(
    options: {
      years?: number;
      refDate?: string | Date | number;
    } = {}
  ): Date;
faker.date.past() // '2021-12-03T05:40:44.408Z'
faker.date.past({ years: 10 }) // '2017-10-25T21:34:19.488Z'
faker.date.past({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2017-08-18T02:59:12.350Z'

See Also

• faker.date.recent(): For generating dates in the recent past (days instead of years).

Source

• View Source

recent

Generates a random date in the recent past.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The optional options object.
options.days?	number	1	The range of days the date may be in the past.
options.refDate?	string | number | Date	faker.defaultRefDate()	The date to use as reference point for the newly generated date.

Returns: Date

function recent(
    options: {
      days?: number;
      refDate?: string | Date | number;
    } = {}
  ): Date;
faker.date.recent() // '2022-02-04T02:09:35.077Z'
faker.date.recent({ days: 10 }) // '2022-01-29T06:12:12.829Z'
faker.date.recent({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2019-12-27T18:11:19.117Z'

See Also

• faker.date.past(): For generating dates further back in time (years instead of days).

Source

• View Source

soon

Generates a random date in the near future.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The optional options object.
options.days?	number	1	The range of days the date may be in the future.
options.refDate?	string | number | Date	faker.defaultRefDate()	The date to use as reference point for the newly generated date.

Returns: Date

function soon(
    options: {
      days?: number;
      refDate?: string | Date | number;
    } = {}
  ): Date;
faker.date.soon() // '2022-02-05T09:55:39.216Z'
faker.date.soon({ days: 10 }) // '2022-02-11T05:14:39.138Z'
faker.date.soon({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-01-01T02:40:44.990Z'

See Also

• faker.date.future(): For generating dates further in the future (years instead of days).

Source

• View Source

weekday

Returns a random day of the week.

Available since v3.0.1

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The optional options to use.
options.abbreviated?	boolean	false	Whether to return an abbreviation.
options.context?	boolean	false	Whether to return the day of the week in the context of a date. In the default en locale this has no effect, however, in other locales like fr or ru, this may affect grammar or capitalization, for example 'Lundi' with { context: false } and 'lundi' with { context: true } in fr.

Returns: string

function weekday(
    options: {
      abbreviated?: boolean;
      context?: boolean;
    } = {}
  ): string;
faker.date.weekday() // 'Monday'
faker.date.weekday({ abbreviated: true }) // 'Thu'
faker.date.weekday({ context: true }) // 'Thursday'
faker.date.weekday({ abbreviated: true, context: true }) // 'Fri'

Source

• View Source