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.

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?	Date | number | string	faker.defaultRefDate()	The date to use as reference point for the newly generated date.

Returns: Date

faker.date.anytime(options: {
  refDate: Date | number | string
} = {}): 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	Date | number | string | { ... }		The optional options object.
options.from	Date | number | string		The early date boundary.
options.to	Date | number | string		The late date boundary.
legacyTo?	Date | number | string		Deprecated, use options.to instead.

Returns: Date

faker.date.between(options: Date | number | string | {
  from: Date | number | string,
  to: Date | number | string
}, legacyTo?: Date | number | string): 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.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	Date | number | string | { ... }		The optional options object.
options.count?	number | { max: number, min: number }	3	The number of dates to generate.
options.from	Date | number | string		The early date boundary.
options.to	Date | number | string		The late date boundary.
legacyTo?	Date | number | string		Deprecated, use options.to instead.
legacyCount?	number	3	Deprecated, use options.count instead.

Returns: Date[]

faker.date.betweens(options: Date | number | string | {
  count: number | {
  max: number,
  min: number
},
  from: Date | number | string,
  to: Date | number | string
}, legacyTo?: Date | number | string, legacyCount?: number = 3): 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.

Available since v7.0.0

Parameters

Name	Type	Default	Description
options	{ ... }	{}	The options to use to generate the birthdate. If no options are set, an age between 18 and 80 (inclusive) is generated.
options.max?	number	80	The maximum age or year to generate a birthdate.
options.min?	number	18	The minimum age or year to generate a birthdate.
options.mode?	'age' | 'year'	'year'	The mode to generate the birthdate. Supported modes are 'age' and 'year' . There are two modes available 'age' and 'year': 'age': The min and max options define the age of the person (e.g. 18 - 42). 'year': The min and max options define the range the birthdate may be in (e.g. 1900 - 2000).
options.refDate?	Date | number | string	faker.defaultRefDate()	The date to use as reference point for the newly generated date.

Returns: Date

faker.date.birthdate(options: {
  max: number,
  min: number,
  mode: 'age' | 'year',
  refDate: Date | number | string
} = {}): Date
faker.date.birthdate() // 1977-07-10T01:37:30.719Z
faker.date.birthdate({ min: 18, max: 65, mode: 'age' }) // 2003-11-02T20:03:20.116Z
faker.date.birthdate({ min: 1900, max: 2000, mode: 'year' }) // 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?	number | { ... }	{}	The optional options object.
options.refDate?	Date | number | string	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.
legacyRefDate?	Date | number | string		Deprecated, use options.refDate instead.

Returns: Date

faker.date.future(options?: number | {
  refDate: Date | number | string,
  years: number
} = {}, legacyRefDate?: Date | number | string): 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.abbr?	boolean	false	Whether to return an abbreviation. DEPRECATED: Use abbreviated instead.
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

faker.date.month(options?: {
  abbr: boolean,
  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?	number | { ... }	{}	The optional options object.
options.refDate?	Date | number | string	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.
legacyRefDate?	Date | number | string		Deprecated, use options.refDate instead.

Returns: Date

faker.date.past(options?: number | {
  refDate: Date | number | string,
  years: number
} = {}, legacyRefDate?: Date | number | string): 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?	number | { ... }	{}	The optional options object.
options.days?	number	1	The range of days the date may be in the past.
options.refDate?	Date | number | string	faker.defaultRefDate()	The date to use as reference point for the newly generated date.
legacyRefDate?	Date | number | string		Deprecated, use options.refDate instead.

Returns: Date

faker.date.recent(options?: number | {
  days: number,
  refDate: Date | number | string
} = {}, legacyRefDate?: Date | number | string): 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?	number | { ... }	{}	The optional options object.
options.days?	number	1	The range of days the date may be in the future.
options.refDate?	Date | number | string	faker.defaultRefDate()	The date to use as reference point for the newly generated date.
legacyRefDate?	Date | number | string		Deprecated, use options.refDate instead.

Returns: Date

faker.date.soon(options?: number | {
  days: number,
  refDate: Date | number | string
} = {}, legacyRefDate?: Date | number | string): 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.abbr?	boolean	false	Whether to return an abbreviation. DEPRECATED: Use abbreviated instead.
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

faker.date.weekday(options?: {
  abbr: boolean,
  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