Basics

boolean#

Return a random boolean value (true or false).

chance.bool();
=> true

character#

Return a random character.

chance.character()
chance.character({ pool: 'abcde' })
chance.character({ alpha: true })
chance.character({ numeric: true })
chance.character({ casing: 'lower' })
chance.character({ symbols: true })

By default it will return a string with random character from the following pool.

'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*()'

Optionally specify a pool and the character will be generated with characters only from that pool.

chance.character({ pool: 'abcde' });
=> 'c'

Optionally specify alpha for an alphabetic character.

chance.character({ alpha: true });
=> 'N'

Optionally specify numeric for a numeric character.

chance.character({ numeric: true });
=> '8'

Default includes both upper and lower case. It's possible to specify one or the other.

chance.character({ casing: Casing.lower });
=> 'j'

Optionally return only symbols

chance.character({ symbols: true });
=> '%'

falsy#

Return a random falsy value (false, null, undefined, 0, NaN, '').

chance.falsy();
chance.falsy({ pool: {null, '', 0} });

By default it will generate any falsy value from this pool

{null, '', 0}

chance.falsy();

The default pool can be change to better meet the needs:

chance.falsy({ pool: {null, ''} });
=> null

floating#

chance.floating()
chance.floating({ fixed: 7 })
chance.floating({ min: 0, max: 100 })

Return a random floating point number.

chance.floating();
=> -211920142886.5024

By default it will return a fixed number of at most 4 digits after the decimal.

Note: at most 4 digits. This because, unless we returned trailing zeroes (which aren't allowed on the JavaScript float) we can't guarantee 4 digits after the decimal. So if random chance comes back with 82383854.2000 then 82383854.2 is what will be returned.

To retrieve a set number of fixed digits after the decimal, provide it as an option.

chance.floating({ fixed: 7 });
=> -749512327.7447168

As with other number functions, can include a min and/or max.

chance.floating({ min: 0, max: 100 });
=> 31.9021

Or combine them.

chance.floating({ min: 0, max: 100, fixed: 8 });
=> 45.92367599

integer#

chance.integer()
chance.integer({ max: 20 })

Return a random integer from 0.

chance.integer();
=> 1293235

This max is inclusive, so it is included in the range. This means

chance.integer({ max: 2 })

would return either 0, 1, or 2.

letter#

Return a random letter.

chance.letter()
chance.letter({ casing: Casing.lower })

By default it will return a random lowercase letter.

chance.letter();
=> 'p'

It's possible to specify upper case

chance.letter({casing:  Casing.upper});
=> 'A'

natural#

chance.natural()
chance.natural({ max: 20 })

Return a natural number.

chance.natural();
=> 125019392395

Can optionally provide a max.

chance.natural({ max: 20});
=> 14

prime#

Return a prime number.

chance.prime()
chance.prime({ min: 1, max: 20 })

Return a prime number.

default range: 0 to 10000

  chance.prime();
  => 929

Can optionally provide a max.

chance.prime({ max: 20});
=> 13

string#

Return a random string.

chance.string()
chance.string({ length: 5 })
chance.string({ pool: 'abcde' })
chance.string({ alpha: true })
chance.string({ casing: 'lower' })
chance.string({ symbols: true })

By default it will return a string with random length of 5-20 characters and will contain any of the following characters.

  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*()[]'

Can optionally specify a length and the string will be exactly that length.

  chance.string({ length: 5 });
  => 'YN%fG'

Can optionally specify a pool and the string will be generated with characters only from that pool.

  chance.string({ pool: 'abcde' });
  => 'cccdeeabedebb'

Of course these options can also be combined.

  chance.string({ length: 5, pool: 'abcde' });
  => 'cbbdc'

All the options for chance.character() are supported:

  chance.string({ length: 8, casing: 'upper', alpha: true, numeric: true });
  => '3THK7GB1'