Chance is a minimalist generator of random [1] strings, numbers, etc. to help reduce some monotony particularly while writing automated tests or anywhere else you need anything random.

Chance is open source software and is released under the developer and business-friendly MIT license.

Chance is loaded on this site so you can just open the console on your browser and play!

Written by Victor Quinn


Download Chance

Or grab the latest version on Github.



It can also be used with Bower

bower install chance

then in the HTML of your app:

<!-- Load Chance -->
<script type="text/javascript" src="bower_components/chance/chance.js"></script>
// Use Chance



Chance instantiates itself onto the window. This means that in the simplest case you can just include the script tag then use an instance of Chance immediately.

<script src="chance.js"></script>

The above snippet would result in either true or false being logged to your console. Note how the instance is lowercase chance. Uppercase Chance is the constructor which will create a new instance of Chance.


You can also ignore the global instantiation of Chance and create your own. This allows you to create multiple instances if you’d like. For convenience, we also bind Chance to window so it’s accessible globally in the browser at window.Chance or just Chance.

<script src="chance.js"></script>
var my_chance = new Chance();


If you create your own instance of Chance, you can provide your own seed if you would like to be repeatable or if you’d like a more truly random seed. In the below example, I am doing an AJAX call to hit to retrieve a true random number which I use to seed Chance.

<script src=""></script>
<script src=""></script>
var mySeed;
$.get("", {num: "1", col: "1", min: "1", max: "1000000000", base: "10", format: "plain", rnd: "new"}, function(randNum) {
mySeed = randNum;

// Instantiate Chance with this truly random number as the seed
var my_seeded_chance = new Chance(mySeed);


To use Chance from the command line, install chance-cli globally with:

npm install -g chance-cli

Then invoke any generator by name followed by options, like so:

$ chance name --prefix true
Dr. Georgia Sanchez

$ chance latitude --min 12.34 --max 56.78

More details in the chance-cli README


It can also be used in Node.js

npm install chance

then in your app

// Load Chance
var Chance = require('chance');

// Instantiate Chance so it can be used
var chance = new Chance();

// Use Chance here.
var my_random_string = chance.string();

As of version 0.5.5, the following is also offered as a convenience for getting an instance of Chance

// Load and instantiate Chance
var chance = require('chance').Chance();

// Use Chance here.
var my_random_string = chance.string();


Load Chance with RequireJS

  require(['Chance'], function(Chance) {
// Instantiate
var chance = new Chance();

// Then use it:
var my_random_integer = chance.integer();


You can also instantiate your own instance of Chance with a known seed. This is useful for creating repeatable results.

var chance1 = new Chance(12345);
var chance2 = new Chance(12345);

// These yield the same values, in sequence

Since both copies of Chance had the same seed, they will both generate the same random number sequence each time they’re called.

This allows for repeatability, if desired.

This is possible because Chance is built atop a Mersenne Twister, a pseudo-random number generator which produces repeatable results given the same seed.

Optionally provide the seed as a string.

var chance1 = new Chance("foo");
var chance2 = new Chance("bar");

// These will be different

Optionally provide multiple arguments as the seed.

var chance1 = new Chance("hold", "me", "closer");
var chance2 = new Chance("tony", "danza");
var chance3 = new Chance("hold", "me", "closer");

// These will be different

// This will be the same as the value from chance1 above


Instead of providing a seed, which will be used to seed our Mersenne Twister, you can also specify an arbitrary function to generate random numbers which the rest of the library will utilize when generating everything else.

A rather simple example, simply using Math.random() instead of our Mersenne Twister

// Use Math.random() instead of our Mersenne Twister
var chance = new Chance(Math.random);

=> '131 Asmun Pike'
=> '261 Pawnaf Highway'

Chance will appear to work just the same, but have a different underlying random generator.

This function should return any number between 0 and 1.



chance.bool({likelihood: 30})

Return a random boolean value (true or false).

=> true

The default likelihood of success (returning true) is 50%. Can optionally specify the likelihood in percent:

chance.bool({likelihood: 30});
=> false

In this case only a 30% likelihood of true, and a 70% likelihood of false.


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

Return a random character.

=> 'v'

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


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 only an alphanumeric character.

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

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

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

Note, wanted to call this key just case but unfortunately that’s a reserved word in JavaScript for use in a switch statement

Optionally return only symbols

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


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

Return a random floating point number.

=> -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


chance.integer({min: -20, max: 20})

Return a random integer.

range: -9007199254740992 to 9007199254740992

See: Largest number in JavaScript

=> -1293235

Can optionally provide min and max.

chance.integer({min: -20, max: 20});
=> -7

These min and max are inclusive, so they are included in the range. This means chance.integer({min: -2, max: 2}); would return either -2, -1, 0, 1, or 2.

// Specific case
-2 <= random number <= 2

// General case
min <= random number <= max


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

Return a random letter.

=> 'p'

By default it will return a random lowercase letter.

It’s possible to specify upper case

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

Note, wanted to call this key just case but unfortunately that’s a reserved word in JavaScript for use in a switch statement


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

Return a natural number.

range: 0 to 9007199254740992

=> 125019392395

Can optionally provide min and max.

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

These are inclusive, so they are included in the range. This means chance.natural({min: 1, max: 3}); would return either 1, 2, or 3 or:

// Specific case
1 <= random number <= 3

// General case
min <= random number <= max

Natural Number on Wikipedia


chance.string({length: 5})
chance.string({pool: 'abcde'})

Return a random string.

=> 'Z&Q78&fqkPq'

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


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'



chance.paragraph({sentences: 1})

Return a random paragraph generated from sentences populated by semi-pronounceable random (nonsense) words.

=> 'Lel fi huepe jupu akse zej ire vesik kojvulom zon is biwuwkef pa. Uv hokivej voh ebu numdogi akolo hik uwlez ta vacev ofdaimi acunetum suvet uhdab ir soglazo ju pafbeb. Pub cezeh fuc kebamnul he ok luumoabi rawkig me fov pin zup biv risugra. Ralpunad apkomgib alnirciw akel wa lus wahfum burog buol vecotihe abadahoj ugolo wovki ucojal fec.'

Default is a paragraph with a random number of sentences from 3 to 7.

Optionally specify the number of sentences in the paragraph.

  chance.paragraph({sentences: 1});
=> 'Idefeulo foc omoemowa wahteze liv juvde puguprof epehuji upuga zige odfe igo sit pilamhul oto ukurecef.'


chance.sentence({words: 5})

Return a random sentence populated by semi-pronounceable random (nonsense) words.

=> 'Witpevze mappos isoletu fo res bi geow pofin mu rupoho revzi utva ne.'

The sentence starts with a capital letter, and ends with a period.

Default is a sentence with a random number of words from 12 to 18.

This length is chosen as the default as it works out to the average English sentence is in that range.

Optionally specify the number of words in the sentence.

  chance.sentence({words: 5});
=> 'Waddik jeasmov cakgilta ficub up.'



Return a semi-speakable syllable, 2 or 3 letters

=> 'fop'

The syllable is returned in all lower case.

A syllable generally alternates between vowel and consanant and is used as the core building block for a word.


chance.word({syllables: 3})
chance.word({length: 5})

Return a semi-pronounceable random (nonsense) word.

=> 'bappada'

The word is returned in all lower case.

Default is a word with a random number of syllables from 1 to 3.

This length is chosen as it works out to the average word length of ~5-6 chars which seems about right.

Can optionally specify a number of syllables which the word will have.

Note these are not syllables in the strict language definition of the word, but syllables as we’ve defined here which is 2 or 3 characters, mostly alternating between vowel and consanant. This is the about the best we can do with purely random generation.

  chance.word({syllables: 3});
=> 'tavnamgi'

Can optionally specify a length and the word will obey that bounding.

  chance.word({length: 5});
=> 'ralve'

In this case these 2 options are mutually exclusive, that is they cannot be combined as they often make no sense. It wouldn’t be possible to have a word with 7 syllables and a length of 5 or a length of 30 but 2 syllables.

Therefore, if both are specified, an Exception will be thrown so the Developer can handle their broken case.

  chance.word({length: 5, syllables: 20});
=> new RangeError("Chance: Cannot specify both syllables AND length.");



chance.age({type: 'child'})

Generate a random age

=> 45

Default range is between 1 and 120

Optionally specify one of a handful of enumerated age types:

chance.age({type: 'child'});
=> 9

Allowed types are: child, teen, adult, senior


chance.birthday({string: true})
chance.birthday({type: 'child'})

Generate a random birthday

=> Fri Aug 16 1985 00:00:00 GMT-0400 (EDT)

By default, returns an actual JavaScript Date object.

Optionally specify it be returned as a string.

chance.birthday({string: true});
=> '4/1/1968'

By default returns in MM/DD/YYYY format. Can specify DD/MM/YYYY as follows:

chance.birthday({string: true, american: false});
=> '28/6/1993'

For more complex date formats, use the Moment library.

Can also specify the type, same types as with age.

chance.birthday({type: 'child'});
=> Sat Sep 08 2001 00:00:00 GMT-0400 (EDT)

You can also compose with chance.year for interesting combinations. For example, let’s say we want to get the birthdays of some renaissance artists (born between 1450 and 1500). We can generate a year and then get a birthday from that year:

var year = chance.year({ min: 1450, max: 1500 });
chance.birthday({ year: year });
=> Wed Aug 27 1484 11:24:14 GMT-0400 (EDT)

// Could be simplified down to one line
chance.birthday({ year: chance.year({ min: 1450, max: 1500 }) });
=> Fri Nov 26 1469 09:17:13 GMT-0500 (EST)


Generate a random Italian social security number (Codice Fiscale).;
=> 'BRSMRT87S49A988X'

Optionally specify any or all components: first name, last name, gender, birth date, place of birth (using ISTAT geocodes for Italian cities).{first: 'Sergio', last: 'Leone'});
=> 'LNESRG93P28F067V'{first: 'Sophia', last: 'Loren', gender: 'Female', birthday: new Date(1934,8,20), city: 'h501'});

=> 'LRNSPH34P60H501G'



Generate a random Brazilian tax id.

=> '607.116.899-62'


chance.first({nationality: 'us'})

Generate a random first name

=> 'Leila'

Optionally specify a gender to limit first names to that gender

Chance.first({ gender: "female" });
=> 'Emma'

Optionally specify a nationality to limit first names to those most common of that nationality

Chance.first({ nationality: "it" });
=> 'Alberto'

Note, currently support for nationality is limited to: 'us', 'it'.



Generate a random gender

=> 'Female'


chance.last({nationality: 'us'})

Generate a random last name

=> 'Mago'

Optionally specify a nationality to limit first names to those most common of that nationality

Chance.last({ nationality: "it" });
=> 'Giovannini'

Note, currently support for nationality is limited to: 'us', 'it'.

name{middle: true}){middle_initial: true}){prefix: true}){nationality: 'en'})

Generate a random name;
=> 'Dafi Vatemi'

Optionally include the middle name{ middle: true });
=> 'Nelgatwu Powuku Heup'

Optionally include the middle initial{ middle_initial: true });
=> 'Ezme I Iza'

Optionally include the prefix{ prefix: true });
=> 'Doctor Suosat Am'

Optionally include the suffix{ suffix: true });
=> 'Fanny Baker Esq.'

Optionally specify a gender{ gender: "male" });
=> "Patrick Copeland"

Optionally specify a nationality{ nationality: "it" });
=> "Roberta Mazzetti"

Note, currently support for nationality is limited to: 'en', 'it'.


chance.prefix({full: true})

Generate a random name prefix

=> 'Mrs.'

By default, returns the shorter version.

Optionally get back the full version.

chance.prefix({ full: true });
=> 'Mister'

Optionally specify a gender. Valid options are male, female, or all (the default).

chance.prefix({ gender: "male" });
=> 'Mr.'

chance.prefix({ gender: "female" });
=> 'Miss'

To maintain legacy support, this also responds to chance.name_prefix().



Generate a random social security number.

=> '411-90-0070'

Optionally provide option of getting only the last four

chance.ssn({ ssnFour: true });
=> '2938'

Optionally specify dashes be removed

chance.ssn({ dashes: false });
=> '293839295'


chance.suffix({full: true})

Generate a random name suffix

=> 'Sr.'

By default, returns the shorter version.

Optionally get back the full version.

chance.suffix({ full: true });
=> 'Juris Doctor'

To maintain legacy support, this also responds to chance.name_suffix().



chance.animal({type: 'zoo'})

Generate a random animal

=> 'Cobra'

Default is any type of animal.

Optionally specify a specific type of animal

chance.animal({type: 'zoo'});
=> 'Lion'

Allowed types are: ocean, desert, grassland, forest, farm, pet, and zoo




Return a random GCM registration ID.

=> 'APA91HHQyPlWqV2Nu61LRs41eE4vrR4bHLKTs0-Dh5nDLopcWZotLw77NEoJyADNJiq6cwY0jMM02y8aacLs6fe2_ynweFjZJVVevKON-32826v-EFoayyThU3-42YEUY9pCScU_n73yRNSOlTk5W6iPtrDkQ3a6_BvOxRbSYi3E6QEY0ZuIQF0'



Return a random Apple Push Token

=> 'b50edac575bfba07dd019b28b2af7189a3ddda17c806ef14a9abbfd00533f67e'



Return a random BlackBerry Device PIN

=> '985de771'



Return a random Windows Phone 7 ANID

=> 'A=3FC2491A0E0C5AB7824B2F60DCE4DB02&E=4e7&W=6'



Return a random Windows Phone 8 ANID2




chance.avatar({protocol: 'https'})
chance.avatar({fileExtension: 'jpg'})
chance.avatar({email: ''})

Return a URL to a random avatar from Gravatar.

=> '//'

By default, a url is returned without a protocol. Specify one to get a random url but with a known protocol

chance.avatar({protocol: 'https'})
=> ''

Optionally specify a file extension to get one of a known type

chance.avatar({fileExtension: 'jpg'})
=> '//'

You can also use it with a known email address to just get that gravatar.

However, note this, of course, no longer makes it random, just more of a helper function:

chance.avatar({email: ''})
=> ''


chance.color({format: 'hex'})
chance.color({grayscale: true})
chance.color({casing: 'upper'})

Return a random color.

=> '#79c157'

Colors have four base types: hex, shorthex, rgb, 0x

These are the kinds usable in HTML or CSS. The type can optionally be specified

chance.color({format: 'hex'})
=> '#d67118'

chance.color({format: 'shorthex'})
=> '#60f'

chance.color({format: 'rgb'})
=> 'rgb(110,52,164)'

chance.color({format: '0x'})
=> '0x67ae0b'

Can optionally specify that only grayscale colors be generated

chance.color({grayscale: true})
=> '#e2e2e2'

Optionally specify casing to get only uppercase letters in the color

chance.color({casing: 'upper'})
=> '#29CFA7'


Return a random company name.
=> 'Caremark Rx Inc'


chance.domain({tld: 'com'})

Return a random domain with a random tld.

=> ''

Optionally specify a tld and the domain will be random but the tld will not.

chance.domain({tld: 'ie'})
=> ''

email{domain: ""})

Return a random email with a random domain.
=> ''

Optionally specify a domain and the email will be random but the domain will not.{domain: ''})
=> ''



Return a random Facebook id, aka fbid.

=> "1000039460258605"



Return a random Google Analytics tracking code. Takes the form 'UA-123456-01'

=> 'UA-384555-17'



Return a random hashtag. This is a string of the form ‘#thisisahashtag’.

=> '#dichumwa'



Return a random IP Address.

=> ''



Return a random IPv6 Address.

=> 'db2f:6123:f99e:00f7:a76e:7f68:9f91:bb08'



Return a random Klout score. Range 1-99.

=> 21


chance.profession({rank: true})

Return a random profession. Rank is false by default.

=> 'Software Test Engineer'

Optionally set rank as true get rank with profession.

chance.profession({rank: true})
=> 'Junior Supply Chain Director'



Return a random tld (Top Level Domain) from the set:

['com', 'org', 'edu', 'gov', 'uk', 'net', 'io']

Note, these do not start with a period.



Return a random twitter handle.

=> "@guspejani"


chance.url({domain: ''})
chance.url({path: 'images'})
chance.url({extensions: ['gif', 'jpg', 'png']})

Return a random url.

=> ''

Optionally specify a domain and the url will be random but the domain will not.

chance.url({domain: ''})
=> ''

Optionally specify a path and it will be obeyed.

chance.url({path: 'images'})
=> ''

Optionally specify an array of extensions and one will be picked at random.

chance.url({extensions: ['gif', 'jpg', 'png']})
=> ''



chance.address({short_suffix: true})

Generate a random street address

=> '5447 Bazpe Lane'

Optionally mandate that it return a short suffix

chance.address({short_suffix: true});
=> '536 Baner Rd'


chance.altitude({ fixed: 7 })
chance.altitude({ max: 1000 })

Generate a random altitude, in meters.

=> 1863.21417

By default, includes 5 digits of accuracy after the decimal. Can override with the fixed option.

chance.altitude({ fixed: 7 })
=> 6897.8978386

By default, max of 8848m (height of Mount Everest), but this can be overridden with the max option.

chance.altitude({ max: 1000 })
=> 890.20665



Generate a random area code

=> '(526)'

Note, this is a US area code, we have little support for internationalization at this time. Hope to fix that in the future!


Generate a random city name;
=> 'Cowotba'


chance.coordinates({fixed: 2})

Generate random coordinates, which are latitude and longitude, comma separated.

=> "-29.52974, 24.52815"

By default includes 5 fixed digits after decimal, can specify otherwise.

chance.coordinates({fixed: 2});
=> "-49.16, 68.81"

country{ full: true })

Return a random country.;
=> 'LT'

By default, returns only the 2 letter ISO 3166-1 code for the country.

Optionally specify that it ought to return a full country name.{ full: true });
=> 'Venezuela'


chance.depth({ fixed: 2 })
chance.depth({ min: -1000 })

Generate a random depth, in meters. Depths are always negative

=> -2126.95039

By default, includes 5 digits of accuracy after the decimal. Can override with the fixed option.

chance.depth({ fixed: 2 })
=> -1542.11

By default, maximum (or minimum depending on your frame of reference) depth of -2550 (depth of the Mariana Trench), but this can be overridden with the min option.

chance.depth({ min: -1000 })
=> -718.41976


chance.geohash({ length: 5 })

Generate a random geohash. More details on what a geohash is.

=> 'h9xhn7y'

By default, includes 7 characters of accuracy. Can override with the length option.

chance.geohash({ length: 5 })
=> 'dr0kr'


chance.latitude({fixed: 7})

Generate a random latitude.

=> 57.99514

range: -90 to 90

By default includes 5 fixed digits after decimal, can specify otherwise.

chance.latitude({fixed: 7});
=> -29.6443133

By default includes entire range of allowed latitudes, can specify a min and/or max to bound it

chance.latitude({min: 38.7, max: 38.9});
=> 38.82358


chance.longitude({fixed: 7})

Generate a random longitude.

=> 149.41549

range: -180 to 180

By default includes 5 fixed digits after decimal, can specify otherwise.

chance.longitude({fixed: 7});
=> 51.4549925

By default includes entire range of allowed longitudes, can specify a min and/or max to bound it

chance.longitude({min: -78, max: -77});
=> -77.22644

phone{ formatted: false }){ country: "fr" }){ country: "fr", mobile: true })

Generate a random phone;
=> '(494) 927-2152'

By default conforms to NANP for a proper US phone number.

Optionally disable formatting.{ formatted: false });
=> '2617613391'

Optionally specify a country.{ country: 'fr' });
=> '01 60 44 92 67'

Note, at current we only have support for 'us', 'uk', or 'fr' for countries.

For uk and fr, optionally specify a mobile phone.{ country: 'uk', mobile: true });
=> '07624 321221'



Return a Canadian Postal code. Returned postal code is valid with respect to the Postal District (first character) and format only.

=> 'R1S 3F4'


chance.province({full: true})
chance.province({full: true})

Return a random province.

=> 'ON'

By default, returns only the 2 letter abbreviation for province.

Optionally specify that it ought to return a full province name.

  chance.province({full: true});
=> 'Nova Scotia'

Optionally specify the country from which it should return the province name.

  chance.province({country: 'it', full: true});
=> 'Vicenza'

Note, currently support for country is limited to: 'ca', 'it'.


chance.state({ full: true })
chance.state({ territories: true })
chance.state({ armed_forces: true })
chance.state({ us_states_and_dc: false })
chance.state({ country: 'us' })

Return a random state.

=> 'AK'

By default, returns only the 2 letter abbreviation for state.

Optionally specify that it ought to return a full state name.

  chance.state({ full: true });
=> 'Florida'

Optionally add U.S. Territories (‘American Samoa’, ‘Federated States of Micronesia’, ‘Guam’, ‘Marshall Islands’, ‘Northern Mariana Islands’, ‘Puerto Rico’, ‘Virgin Islands, U.S.’) to the mix of randomly selected items:

  chance.state({ territories: true, full: true })
=> 'Guam'

Optionally add Armed Forces to the list as well:

  chance.state({ armed_forces: true, full: true })
=> 'Armed Forces Pacific'

For all U.S. states, territories, and armed forces, specify all of them:

  chance.state({ armed_forces: true, territories: true })
=> 'NY'

For just territories or armed forces, specify that it ought not return U.S. states:

  chance.state({ territories: true, us_states_and_dc: false })
=> 'PR'

Optionally specify a country (US specific options are ignored if country is specified and different from 'us'):

  chance.state({ country: 'it', full: true })
=> 'Toscana'



Generate a random street

=> 'Tesca Circle'

Optionally mandate that it returns a short suffix

  chance.street({short_suffix: true});
=> 'Jiled St'

Optionally specify the number of syllables used to generate the street name

  chance.street({syllables: 8});
=> 'Teniefitinusewjircor Junction'

Optionally specify a country to localize street prefixes

  chance.street({country: 'it'});
=> 'Via Nefba'

Note, currently support for country is limited to: 'us', 'it'.

zip{plusfour: true})

Generate a random (U.S.) zip code.;
=> '90210'

Can optionally specify that it ought to return a Zip+4:{plusfour: true});
=> '01035-1838'


For more complex time manipulation, Moment is strongly recommended. It would be out of this library's core competency to try and provide date objects of all formats



Return am or pm. Very simple.

=> 'am'

date{string: true}){string: true, american: false}){year: 1983})

Generate a random date;
=> Sat Apr 09 2072 00:00:00 GMT-0400 (EDT)

By default, returns an actual Date object

Can optionally specify that a date be returned as a string{string: true});
=> "5/27/2078"

This will return a date string of the format MM/DD/YYYY.

Now of course MM/DD/YYYY is the “American” date method, but it’s the default because there isn’t much support for internationalization here yet. Further, it’s the format used by Facebook and other services for birthdays and other non-Date object dates.

However, we support returning dates in DD/MM/YYYY format as well when requesting a date by a string and passing american: false.{string: true, american: false});
=> "13/2/2017"

If you want richer control over date format, strongly suggest using the Moment library. Our formatting is very minimalist, and it’s out of our core competency to offer dates in a myriad of formats.

Can optionally specify defaults for any of day, month, or year.{year: 1983});
=> Wed May 04 1983 00:00:00 GMT-0400 (EDT){month: 0});
=> Tue Jan 18 2084 00:00:00 GMT-0500 (EST){day: 21});
=> Sun Oct 21 2103 00:00:00 GMT-0400 (EDT)

A random date is generated, but the default you specify is kept constant.

Note, month is 0-indexed. This is a carryover from the core JavaScript Date object which we use internally to generate the date. We considered



Generate a random hammertime.

=> 2273327300317

Hammertime is the name given to a Unix time with milliseconds. Which is the same as saying the number of milliseconds since 1970. It has finer granularity than a normal Unix timestamp and thus is often used in realtime applications.

According to startup lore, Hammertime was coined by a startup whose founder had an interesting interaction with M.C. Hammer. There was no name given to “Unix time with milliseconds” and while brainstorming ideas (because Unix time with milliseconds is a confusing mouthful), someone suggested Hammertime and it stuck.


chance.hour({twentyfour: true})

Generate a random hour

=> 9

By default, returns an hour from 1 to 12 for a standard 12-hour clock.

Can optionally specify a full twenty-four.

  chance.hour({twentyfour: true});
=> 21

This will return an hour from 1 to 24.



Generate a random millisecond

=> 729

By default, returns a millisecond from 0 to 999. Idea is for generating a clock time.



Generate a random minute

=> 35

By default, returns a minute from 0 to 59. Idea is for generating a clock time.



Generate a random month.

=> 'January'

By default, returns just the full name.

Optionally specify raw to get the whole month object consisting of name, short_name, and numeric.

  chance.month({raw: true});
=> {name: 'October', short_name: 'Oct', numeric: '10'}



Generate a random second

=> 19

By default, returns a second from 0 to 59. Idea is for generating a clock time.



Generate a random timestamp. This is a standard Unix time, so a random number of seconds since January 1, 1970.

=> 576556683



Return a random timezone

=> {
"name": "India Standard Time",
"abbr": "IST",
"offset": 5.5,
"isdst": false,
"text": "(UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi",
"utc": ["Asia/Calcutta"]


chance.weekday({weekday_only: true})

Return a weekday

=> 'Tuesday'

By default, weekday_only is false. If set to true it will never return Saturday or Sunday.


chance.year({min: 1900, max: 2100})

Generate a random year

=> '2053'

By default, min is the current year and max is 100 years greater than min.

This is returned as a string. If for some reason you need it numeric, just parse it:

=> 2042

Optionally specify min, max, or both to limit the range.

  chance.year({min: 1900, max: 2100});
=> '1983'


cc{type: 'Mastercard'})

Generate a random credit card number. This card number will pass the Luhn algorithm so it looks like a legit card.;
=> '6304038511073827'

Optionally specify a particular type of card to return:{type: 'Mastercard'});
=> '5171206237468496'

The type can be specified by the long name, or by the short name:{type: 'mc'});
=> '5103820202214116'

The types are enumerated below.


chance.cc_type({raw: true})

Return a random credit card type.

=> 'Visa'

Default returns just the name. To return the entire object (consisting of name, short name, numeric prefix, and length), specify so with the raw flag.

  chance.cc_type({raw: true});
=> {name: 'Discover Card', short_name: 'discover', prefix: '6011', length: 16}

The available types are (name - short_name):

  • American Express - amex
  • Bankcard - bankcard
  • China UnionPay - chinaunion
  • Diners Club Carte Blanche - dccarte
  • Diners Club enRoute - dcenroute
  • Diners Club International - dcintl
  • Diners Club United States & Canada - dcusc
  • Discover Card - discover
  • InstaPayment - instapay
  • JCB - jcb
  • Laser - laser
  • Maestro - maestro
  • Mastercard - mc
  • Solo - solo
  • Switch - switch
  • Visa - visa
  • Visa Electron - electron



Generate a random currency.

=> { code: "TVD", name: "Tuvalu Dollar" }



Generate a currency pair. Handy for simulating currency conversions. Guaranteed to return a unique pair (and not the same currency twice).

=> [{ code: "ALL", name: "Albania Lek" }, { code: "ZWD", name: "Zimbabwe Dollar" }]


chance.dollar({max: 250})

Return a random dollar amount.

=> "$2560.27"

=> "$750.99"

By default returns dollar amount no larger than 10000. Optionally specify the max to make it larger (or smaller).

chance.dollar({max: 20});
=> "$15.23"

chance.dollar({max: 10000000})
=> "$5051205.49"


chance.euro({max: 250})

Return a random euro amount. Formatting depends on the current locale (samples are displayed with european formatting)

=> "2.560,27€"

=> "750.99€"

By default returns euro amount no larger than 10000. Optionally specify the max to make it larger (or smaller).

chance.euro({max: 20});
=> "15,23€"

chance.euro({max: 10000000})
=> "5.051.205,49€"


chance.exp({raw: true})

Generate a random credit card expiration.

=> '10/2020'

Optionally specify that a raw object be returned rather than a string

  chance.exp({raw: true});
=> {month: '11', year: '2017'}


chance.exp_month({future: true})

Generate a random credit card expiration month.

=> '01'

Optionally specify that it must be a later month than the current month.

chance.exp_month({future: true});
=> '10'

So if called in June, this would return a random month from July - Dec. If called in October, would return November or December.

This because many credit card sandboxes require an expiration date later than the current date so it’s necessary when generating an expiration with the current year to generate a month later than the current month.



Generate a random credit card expiration year.

=> '2018'

Returns a random year between today and 10 years in the future.




Capitalize the first letter of a word

=> 'Bread'



Mixins are a very powerful way to extend Chance to fit the needs of your specific application.

First, if you are thinking of using a mixin for Chance, please consider first whether your use is something from which others may benefit. If so, please submit a pull request rather than using a mixin!

Spread the love and give everyone the benefit of your awesome generator :)

Now, that said, there are bound to be times when you want to generate something random that is specific to your application but not widely applicable. Enter mixins!

Chance mixins allow you to add one-off methods to Chance which you can use later.

For example, let’s say I have a user object which consists of first, last, and email.

var user = {
first: 'John',
last: 'Smith',
email: ''

Let’s say I want to be able to randomly generate these user objects.

This is not the type of thing which would be widely applicable as it’s specific to my application so it’s perfect for a mixin!

To create a mixin, build an object whose keys are the names of the methods, and whose values are the functions to be called.

Note: Within each function, you will have access to chance itself!

For example, to create a user mixin:

'user': function() {
return {
first: chance.first(),
last: chance.last(),

// Then you can call your mixin

=> {first: 'Eli', last: 'Benson', email: ''}

Mixins can even include other mixins!

For example, to “extend” the user object:

'user': function () {
return {
first: chance.first(),
last: chance.last(),
'social_user': function () {
var user = chance.user(); = chance.pick(['facebook', 'twitter']);
return user;

So we have a second mixin here, social_user which is using the user mixin and adding to it! Note, these mixins can be defined in any order on the object if both declared at once.


chance.pad(number, width)
chance.pad(number, width, padder)

Pad a number with some string until it reaches a desired width.

By default, chance.pad() will pad with zeroes. For example, to zero-pad numbers such that the outcome width is 5, do the following.

chance.pad(45, 5)
=> '00045'

chance.pad(284, 5)
=> '00284'

chance.pad(82843, 5)
=> '82843'

Notice how every item returned is a string with leading zeroes until the width is 5 for each one.

Can optionally specify a character if the desire is to pad with something other than zero.

chance.pad(81, 5, 'Z')
=> 'ZZZ81'

chance.pad(692, 5, 'Z')
=> 'ZZ692'

chance.pad(52859, 5)
=> '52859'


chance.pick(array, count)

pick() is now deprecated in favor of pickone() and pickset()



Given an array, pick a random element and return it

  chance.pickone(['alpha', 'bravo', 'charlie', 'delta', 'echo']);
=> 'delta'


chance.pickset(array, quantity)

Given an array, pick some random elements and return them in a new array

  chance.pickset(['alpha', 'bravo', 'charlie', 'delta', 'echo'], 3);
=> ['echo', 'alpha', 'bravo']

Optionally omit the quantity to retrieve a set with length 1

  chance.pickset(['alpha', 'bravo', 'charlie', 'delta', 'echo']);
=> ['delta']


chance.set(key, value)

Used for overriding the default data used by Chance.

For example, if instead of the default set of last names (which were pulled from the U.S. census data and therefore obviously American biased), you could replace the data for the first names with something more suited to your task. For example, if you want instead to pick from last names of houses in A Song of Ice and Fire, you could do something like:

chance.set('lastNames', ['Arryn', 'Baratheon', 'Bolton', 'Frey', 'Greyjoy', 'Lannister', 'Martell', 'Stark', 'Targaryen', 'Tully', 'Tyrell']);

// then
=> 'Lannister'

This is very handy for internationalization.

Available keys for datasets to override: firstNames, lastNames, provinces, us_states_and_dc, territories, armed_forces, street_suffixes, months, cc_types, currency_types



Given an array, scramble the order and return it.

chance.shuffle(['alpha', 'bravo', 'charlie', 'delta', 'echo']);
=> ['echo', 'delta', 'alpha', 'charlie', 'bravo']

Miscellaneous methods



Flip a coin!

=> 'heads'

=> 'tails'



Return a value equal to the roll of a die.

=> 13

=> 4

These are just wrappers around natural() but are convenient for use by games.


chance.guid({version: 5})

Return a random guid, version 5 by default.

=> 'f0d8368d-85e2-54fb-73c4-2d60374295e3'
chance.guid({version: 4});
=> 'c71f58e3-34af-43c0-b405-2764d6947d21'


chance.hash({length: 25})
chance.hash({casing: 'upper'})

Return a random hex hash

=> 'e5162f27da96ed8e1ae51def1ba643b91d2581d8'

By default, the hash is lowercase and 40 hex characters long (same as a git commit hash).

Optionally specify a length

chance.hash({length: 15})
=> 'c28f57cb599ada4'

Optionally specify casing to get a hash with only uppercase letters rather than the default lowercase

chance.hash({casing: 'upper'})
=> '3F2EB3FB85D88984C1EC4F46A3DBE740B5E0E56E'



These aren’t really hidden per se, but just utility methods intended to be used internally but exposed externally in case they’re useful to anyone.

  // Return the list of cc types
=> [{name: "American Express", short_name: 'amex', prefix: '34', length: 15}, ...]

// Return a new Mersenne Twister
=> [object Object] // An instance of a Mersenne Twister

// Optionally provide a seed for that twister
=> [object Object] // An instance of a twister with seed 12345

// Return our list of name prefixes
=> [{name: 'January', short_name 'Jan', numeric: '01'}, ...]

// Return our list of name prefixes
=> [{name: 'Doctor', abbreviation: 'Dr.'}, {name: 'Miss', abbreviation: 'Miss'}, ...]

// Return the list of provinces
=> [{name: 'Alberta', abbreviation: 'AB'}, {name: 'British Columbia', abbreviation: 'BC'}, ...]

// Return the list of states
=> [{name: 'Alabama', abbreviation: 'AL'}, {name: 'Alaska', abbreviation: 'AK'}, ...]

// Return a random street suffix
=> {name: 'Street', abbreviation: 'St'}

// Return the list of street suffixes
=> [{name: 'Avenue', abbreviation: 'Ave'}, {name: 'Boulevard', abbreviation: 'Blvd'}, ...]


chance.n(, 5)
chance.n(, 5, { domain: "" })

Provide any function that generates random stuff (usually another Chance function) and a number and n() will generate an array of items with a length matching the length you specified.

For example, to generate 5 email addresses:

chance.n(, 5);
=> [ '',
'' ]

Any options that would be sent to the random function can be added following the number.

For example, has options which can be specified, so you can generate 5 emails with a known domain as follows:

chance.n(, 5, { domain: "" })
=> [ '',
'' ]

Note, these items are not guaranteed to be unique. If that is the intent, see chance.unique()


chance.normal({mean: 100})
chance.normal({mean: 100, dev: 15})

Return a normally-distributed random variate.

=> 0.4244767651300604

By default this starts with a mean of 0 and a standard deviation of 1 which is the standard normal distribution.

Optionally specify a mean and/or deviation.

// Notice, since no deviation was specified, using the default of `1`
chance.normal({mean: 100})
=> 99.68352269988522

// For example, to get a random IQ (which by definition has a mean of 100
// and a standard deviation of 15)
chance.normal({mean: 100, dev: 15})
=> 85.11040121833615

Used in combination with the above generators, this can be an extremely powerful way to get more realistic results as often “pure random” results fail to approximate the real world.


Generate a random radio call sign.;
=> 'KCXW'

Optionally specify a side of the Mississippi River to limit stations to that side.

See K and W for more details{side: 'east'});
=> 'WKOQ'{side: 'east'});
=> 'WNOW'


chance.rpg('#d#', {sum: true})

Given an input looking like #d#, where the first # is the number of dice to roll and the second # is the max of each die, returns an array of dice values.

=> [1, 6, 9]

=> [3, 1, 2, 5, 2]

Optionally specify a sum be returned rather than an array of dice.

chance.rpg('3d10', {sum: true});
=> 14

tv{side: 'west'})

Generate a TV station call sign. This is an alias for radio() since they both follow the same rules.;
=> 'WXTY'

Optionally specify a side of the Mississippi River to limit stations to that side.{side: 'west'});
=> 'KCYL'{side: 'west'});
=> 'KQDV'


chance.unique(chance.state, 5)
chance.unique(chance.state, 5, { comparator: func })

Provide any function that generates random stuff (usually another Chance function) and a number and unique() will generate a random array of unique (not repeating) items with a length matching the one you specified.

chance.unique(chance.state, 5);
=> ["SC", "WA", "CO", "TX", "ND"]

This is helpful when there are a limited number of options and you want a bunch but want to ensure each is different.

Optionally specify the comparator used to determine whether a generated item is in the list of already generated items. By default the comparator just checks to see if the newly generated item is in the array of already generated items. This works for most simple cases (such as chance.state()) but will not work if the generated item is an object (because the Array.prototype.indexOf() method will not work on an object since 2 objects will not be strictly equal, ===, unless they are references to the same object).

chance.unique(chance.currency, 2, {
comparator: function(err, val) {
return arr.reduce(function(acc, item) {
return acc || (item.code === val.code);
}, false);
=> [{ code: "KYF", name: "Cayman Islands Dollar" }, { code: "CDF", name: "Congo/Kinshasa Franc" }]

You can also specify any arbitrary options in this third argument and they’ll be passed along to the method you specify as the first.

For example, let’s say you want to retrieve 10 unique integers between 0 and 100. This is easily achievable by specifying chance.integer as hte function, 10 as the number to retrieve, and a min/max in the options.

chance.unique(chance.integer, 10, {min: 0, max: 100});
=> [78, 49, 7, 87, 59, 89, 84, 62, 60, 63]

Note, there could be cases where it is impossible to generate the unique number. For example, if you choose chance.state as shown above as the random function and want say, 55 uniques, Chance will throw a RangeError because it is impossible to generate 55 uniques because there are only 51 states in the available pool (50 states plus the District of Columbia).

chance.unique(chance.state, 55);
=> RangeError: Chance: num is likely too large for sample set


chance.weighted(['a', 'b'], [100, 1])
chance.weighted(['a', 'b', 'c', 'd'], [1, 2, 3, 4])

Provide an array of items, and another array of items specifying the relative weights and Chance will select one of those items, obeying the specified weight.

For example, the following code:

chance.weighted(['a', 'b'], [100, 1]);
=> 'a'

Will generate 'a' 100 times more often than 'b' but still choose one or the other randomly.

The weights are all relative, so if you have more than just two it will ensure that all items are generated relative to all of the weights.

For example, the following code:

chance.weighted(['a', 'b', 'c', 'd'], [1, 2, 3, 4]);
=> 'c'

Will generate a letter from the array but will pick 'b' twice as often as it picks 'a' and will pick 'c' three times as often as it picks 'a' and will pick 'd' four times as often as it will pick 'a' and will pick 'd' two times as often as it will pick 'b'.

The weights can be whole numbers as shown above or fractions.

chance.weighted(['a', 'b', 'c', 'd'], [0.1, 0.2, 0.3, 0.4]);
=> 'd'

There is no requirement that the weights sum to anything in particular, they are all compared relative to each other so all of the following are equivalent:

chance.weighted(['a', 'b', 'c', 'd'], [1, 2, 3, 4]);
chance.weighted(['a', 'b', 'c', 'd'], [0.1, 0.2, 0.3, 0.4]);
chance.weighted(['a', 'b', 'c', 'd'], [100, 200, 300, 400]);
chance.weighted(['a', 'b', 'c', 'd'], [17, 34, 51, 68]);
chance.weighted(['a', 'b', 'c', 'd'], [0.17, 0.34, 0.51, 0.68]);

Recall JavaScript has first class functions so you could do something like the following:

chance.weighted([chance.fbid, chance.twitter, chance.ip], [10, 5, 1])();
=> 10000345166213

That will pick one of the Chance methods with the relative weights specified and then immediately invoke it, so it will return a random fbid twice as often as it will return a twitter handle (because 10/5 is 2) and an fbid 10 times more often than it will return a random ip address (because 10/1 is 10). It will return a random twitter handle 5 times more often than it will return an ip address (because 5/1 is 5).


Change Log

1.0.0 12 Feb 2016diff

  • Long overdue version bump. The Chance API has long been stable and should have had major version 1 long ago.
  • Added new generators: file(), semver(), weekday()
  • Split apart pick() into pickone() and pickset(). The old pick() was very confusing, returning one item if no length supplied or an array if a multiple was supplied. Breaking these apart should make things far less confusing. Deprecated pick()
  • More options for color() and first() and last() and word() and syllable()
  • Bugfixes

0.8.0 11 Sep 2015diff

  • Moved the CLI out into its own repo/project, now at Minor version bump due to this potentially breaking change.
  • Added new generators: country(), mrz(), avatar(), md5()
  • Better jsdoc comments
  • Automated coveralls test coverage report
  • Bugfixes

0.7.0 05 Dec 2014diff

  • Now with cli support! after npm install -g chance you can run chance <generator_name> on the command line and get a random result! Many thanks @oliversalzburg for this excellent addition!
  • Added new generators: android_id(), bb_pin(), cpnj(), suffix(), wp7_anid(), wp8_anid(), url()
  • Now with webworker support
  • Now with UK and France phones
  • Now allowing strings to be provided as the seed for more convenient testing

0.6.1 03 Sep 2014diff

  • Add a bunch of new generators including: altitude(), apple_token() cpf(), currency(), currency_pair(), depth(), geohash(), get(), mac_address(), n(), set(), ssn(), unique(), weighted()
  • Data now separated and replaceable via set(). Much better for internationalization or cases where the defaults are inadequate.
  • New options for:
    • email() - can now specify length of word before @
    • name_prefix() - now can specify gender
  • Possibly breaking changes (from 0.5.x):
    • age() - now default age range is far more sensical but this means it is generally lower (default max used to be 120 now only 65)
    • guid() - now returns all lowercase to accord with the majority of uses in the wild
    • states() - now only returns US states by default, territories and armed forces by flag

0.5.5 16 Mar 2014diff

  • Add range parameters to latitude() and longitude() so range can be bounded
  • Add pad() helper
  • Add google_analytics generator
  • Now allowing for creation of chance instance without using the new keyword to simplify usage in Node.js

0.5.4 17 Dec 2013diff

  • Add tv()
  • Fix issue with negative dollar amounts
  • Fix component.json so it works as expected

0.5.3 08 Nov 2013diff

  • Revamp date() a bit to fix a bug, clean up the code, add finer grained randomity
  • Add hammertime(), second(), millisecond()

0.5.2 05 Nov 2013diff

  • Incorporate valid GUID generator pull request
  • Add support for component

0.5.1 29 Oct 2013diff

  • Fix a minor bug in the new date() function. See Issue 32 on Github for more details.

0.5.0 27 Oct 2013diff

  • Bugfixes: shuffle() was destroying incoming array, color() was ignoring default options
  • Tweaks to existing methods: allow pick() to return multiple elements, better first() and last() using actual names
  • Added yet more generators: age(), birthday(), date(), gender(), hashtag(), klout()
  • Now with Mixin support for extending Chance!

0.4.3 31 Jul 2013diff

  • Added yet more generators: color(), hash()
  • Major refactor of options handling to be much more DRY
  • Now with NANP support for phones
  • Other misc. refactoring to make things more clean

0.4.2 25 Jul 2013diff

  • Added yet more generators, rpg(), d30()
  • Added support for Bower

0.4.1 25 Jul 2013diff

  • Added yet more generators, radio(), shuffle(), ipv6()

0.4.0 18 Jul 2013diff

  • Added a ton more generators
  • Added floating point generation
  • Added ability to specify arbitrary random function
  • Added minified version

0.3.3 01 Jul 2013diff

  • Add floating()
  • Add latitude(), longitude(), coordinates() using floating() as the base

0.3.2 01 Jul 2013diff

  • Incorporate more pull requests for bug fixes
  • Now with Travis CI for automated running of tests
  • Add first(), last() and prefix()

0.3.1 25 Jun 2013diff

  • Added domain(), email(), and ip()
  • Pulled in some pull requests to fix minor bugs

0.3.0 23 Jun 2013diff

  • Updated README to include more info on usage
  • Added most text generators for character, string, syllable, word, phone number, more
  • Added name generators
  • Added address generators and guid

0.2 22 Jun 2013diff

  • Now with a Mersenne Twister rather than Math.random() as the base so tests are repeatable.
  • Restructured Chance as a module rather than a singleton
  • Constructor now takes a seed which can be used to instantiate a new copy with a Mersenne Twister base
  • Added some dice

0.2.1 22 Jun 2013diff

  • Updated README to include more info on usage
  • Added most text generators for character, string, syllable, word
  • Added address generators and guid

Acknowledgements & Thanks

This documentation is based on the layout of the Zepto.js which itself is based on the layout of the Backbone.js documentation, which is released under the MIT license.

Thank you to Sean McCullough for your Mersenne Twister gist on which almost the entirety of this library is dependent. And to Takuji Nishimura and Makoto Matsumoto who wrote the original C version on which Sean's JavaScript gist is based.

And of course a monster thank you to all of the Contributors to this project!

© 2013 Victor Quinn
Chance and this documentation are released under the terms of the MIT license.