provides a rank for a poker hand, potentially including wildcards

Usage no npm install needed!

<script type="module">
  import pokerRanking from '';



Evaluates a poker hand - can include options such as wild cards or whether Ace can act as a low card


The exposed functions from this library are evaluateHand which returns a string saying what the hand represents and evaluateAndFindCards. which will return a string and the cards from the input array which form this hand.

evaluateHand(cards options)
evaluateAndFindCards(cards options)

The arguments to these functions are:

  • cards - an array of strings representing the hand. Strings should be a 2 or 3 character string representing the rank and suit (for example, '10S' for 10 of spades or 'QD' for Queen of diamonds). The string can also be 'joker' which represents a wild card (jokers are always wild and need not be specified in the wildCard array)
  • options - an array of options for evaluating the hand as noted below

The options structure is composed of the following fields with the following default values:

  aceCanBeLow:false,  // Whether Ace can be considered a low card in a straight
  wildCards:[],       // An array of strings representing wild cards.
                      // This can either be a rank (e.g. '2') to indicate
                      // all cards of a rank are wild, or specific cards
                      // (e.g. ['JH', 'JS'] to indicate one-eyed jacks)
  cardsToEvaluate:5,  // The number of cards to consider when evaluating the hand.
                      // Ignored if set more than 5 or number of cards in hand
  dontAllow:[],       // An array of hand types to ignore
                      // For example, to not consider a straight or flush for
                      // a 3-card hand, you would set this field to
                      // ['straight', 'flush', 'straightflush']
  minPair:undefined,  // A minimal value to consider for a pair
                      // If there is one pair and it meets or exceeds this
                      // minimum the return value will be `minpair`
                      // (e.g. set to 'J' for jacks or better)

The return value is one of the following strings, in order from highest-ranked to lowest-ranked hand:

  • 5ofakind
  • royalflush
  • straightflush
  • 4ofakind
  • fullhouse
  • flush
  • straight
  • 3ofakind
  • 2pair
  • pair (minpair if minpair option specified and pair meets or exceeds this)
  • nothing

For evaluateHand this string is the return value. For evaluateAndFindCards, the return value is a structure with two fields:

  match,      // One of the above mentioned strings
  cards:[],   // The cards from the input array that compose this hand

Note that cards will always be the best set of cards which make up this hand. For exapmle, if given a 7-card hand with all spades, it will return the 5 highest-ranked spades in the hand.