Skip to content

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

NameTypeDefaultDescription
options{ ... }{}

The optional options object.

options.refDate?Date | number | stringfaker.defaultRefDate()

The date to use as reference point for the newly generated date.

Returns: Date

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

between

Generates a random date between the given boundaries.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
optionsDate | number | string | { ... }

The optional options object.

options.fromDate | number | string

The early date boundary.

options.toDate | number | string

The late date boundary.

legacyTo?Date | number | string

Deprecated, use options.to instead.

Returns: Date

ts
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'

betweens

Generates random dates between the given boundaries.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
optionsDate | number | string | { ... }

The optional options object.

options.count?number | { max: number, min: number }3

The number of dates to generate.

options.fromDate | number | string

The early date boundary.

options.toDate | number | string

The late date boundary.

legacyTo?Date | number | string

Deprecated, use options.to instead.

legacyCount?number3

Deprecated, use options.count instead.

Returns: Date[]

ts
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
// ]

birthdate

Returns a random birthdate.

Available since v7.0.0

Parameters

NameTypeDefaultDescription
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?number80

The maximum age or year to generate a birthdate.

options.min?number18

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 | stringfaker.defaultRefDate()

The date to use as reference point for the newly generated date.

Returns: Date

ts
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

future

Generates a random date in the future.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options?number | { ... }{}

The optional options object.

options.refDate?Date | number | stringfaker.defaultRefDate()

The date to use as reference point for the newly generated date.

options.years?number1

The range of years the date may be in the future.

legacyRefDate?Date | number | string

Deprecated, use options.refDate instead.

Returns: Date

ts
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'

month

Returns a random name of a month.

Available since v3.0.1

Parameters

NameTypeDefaultDescription
options?{ ... }{}

The optional options to use.

options.abbr?booleanfalse

Whether to return an abbreviation.

DEPRECATED: Use abbreviated instead.

options.abbreviated?booleanfalse

Whether to return an abbreviation.

options.context?booleanfalse

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

ts
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'

past

Generates a random date in the past.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options?number | { ... }{}

The optional options object.

options.refDate?Date | number | stringfaker.defaultRefDate()

The date to use as reference point for the newly generated date.

options.years?number1

The range of years the date may be in the past.

legacyRefDate?Date | number | string

Deprecated, use options.refDate instead.

Returns: Date

ts
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'

recent

Generates a random date in the recent past.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options?number | { ... }{}

The optional options object.

options.days?number1

The range of days the date may be in the past.

options.refDate?Date | number | stringfaker.defaultRefDate()

The date to use as reference point for the newly generated date.

legacyRefDate?Date | number | string

Deprecated, use options.refDate instead.

Returns: Date

ts
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'

soon

Generates a random date in the near future.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options?number | { ... }{}

The optional options object.

options.days?number1

The range of days the date may be in the future.

options.refDate?Date | number | stringfaker.defaultRefDate()

The date to use as reference point for the newly generated date.

legacyRefDate?Date | number | string

Deprecated, use options.refDate instead.

Returns: Date

ts
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'

weekday

Returns a random day of the week.

Available since v3.0.1

Parameters

NameTypeDefaultDescription
options?{ ... }{}

The optional options to use.

options.abbr?booleanfalse

Whether to return an abbreviation.

DEPRECATED: Use abbreviated instead.

options.abbreviated?booleanfalse

Whether to return an abbreviation.

options.context?booleanfalse

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

ts
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'

Released under the MIT License.