Under the hood

How Potluck Wheel works

A plain-language walk through what happens between pressing Spin and seeing your table, based on the code that runs in your browser.

Potluck Wheel looks like a game, but the spinning wheel is mostly a reveal. The actual decision about who brings what is made by a short procedure that runs entirely in your browser. This page explains that procedure step by step so you can trust the result, explain it to your group, and use target counts well.

Step 1: reading the guest list

You can type names one per line, or separate them with commas or semicolons. The tool splits the text on new lines, commas, and semicolons, trims spaces from each name, and drops anything empty. That means "Ana, Ben; Chris" and three separate lines produce the same list of three people.

Duplicate names are kept. If you type "Maya" twice, Maya gets two assignments. This is deliberate: it is an easy way to give a household or a generous cook two dishes. If you did not mean to repeat a name, remove the duplicate before spinning.

Step 2: choosing categories

There are five categories: appetizer, main, side, dessert, and drinks. You can turn any of them off, but at least one must remain. Only the checked categories take part in the assignment. For each checked category, you can optionally enter a target count: the number of people you want in that category.

Step 3: a fresh random seed

Each spin starts by creating a new random seed, a number built from the current time and your browser's ordinary random number generator. The rest of the assignment uses a small pseudo-random generator started from that seed. The same seed and the same inputs always produce the same result.

This randomness is meant for fair, practical meal planning. It is not designed for raffles, prizes, or anything where people might have money at stake.

Step 4: deciding how many people go in each category

This is the heart of the tool, and it happens before anyone's name is matched to a category. The goal is a count for each category that adds up to the number of guests.

First, the categories are put in a shuffled order. This order is used to break ties, so no single category always wins when two are equal.

Second, targets are filled. If you set any target counts, the tool fills them one person at a time. At each step it looks for the category that is furthest below its target and adds one person there. It keeps going until every target is met or until it runs out of people. If your targets add up to more than the number of guests, the categories most below their targets get people first, so the shortfall is spread rather than piled onto one category.

Third, leftovers go to the smallest category. Any remaining people are handed out one at a time, each going to whichever selected category currently has the fewest people, with ties broken by the shuffled order. This step also runs when you set no targets at all, which is why an untargeted spin spreads people as evenly as possible. With twelve guests and five categories, for example, you will see two categories with three people and three categories with two.

The effect is that extra people never pile into one category while another is still short. A category you gave a target to can receive extra people too, but only once it is tied for the smallest.

Step 5: matching people to categories

Once the counts are set, the tool builds a list of slots, for example three "main" slots, three "side" slots, and two of each other category. It shuffles the list of people and shuffles the list of slots, then pairs them up in order. Every person gets exactly one slot, and every slot is filled.

Because both lists are shuffled, who ends up in which category is random, while how many people are in each category follows the fair counts from step 4.

Step 6: the spin and the results

The wheel then spins and lands on one of the assignments, picked from the same seeded generator, as a fun reveal. The full results appear grouped by category, so you can see at a glance who is on mains, sides, and so on.

From there you can:

• Copy list: copies a plain-text list grouped by category, ready to paste into email or a group chat.
• Copy share link: copies a link that reopens this exact table.
• Print: uses your browser's print dialog for a paper copy, handy for a fridge or bulletin board.
• Spin again: runs the whole process with a new seed if you want a different arrangement.

How share links work

A share link is the normal Potluck Wheel address with extra text after a #. That text, called the URL hash or fragment, contains the guest names, selected categories, targets, seed, assignments, and which assignment the wheel landed on. It is packed as JSON and encoded in a URL-safe form of Base64, starting with p1. so the tool can recognize it.

When someone opens the link, the page reads the hash, decodes it, checks that the categories are valid, and shows the same table. Browsers do not send the part after # to the web server when loading a page, so the list itself is not uploaded to Potluck Wheel's hosting to load the shared table. It is still plain data inside the link, though. Anyone with the link can see the names, and the link can stay in chat histories and browser history. Share it only with people you intend to include. The privacy page has more detail.

Share links always open the main Potluck Wheel page, so the person you send it to sees the same guides and explanations as anyone else.

Worked example

Suppose you have fourteen names, all five categories selected, and a target of five for mains.

1. The target step puts five people in mains.
2. Nine people remain. The other four categories are all at zero, so they each receive one person in shuffled order, then a second each, which uses eight people.
3. One person remains. Appetizers, sides, desserts, and drinks are tied at two, and mains has five, so the last person goes to whichever of the tied four comes first in the shuffled order.

The final counts are five mains, one category with three, and three categories with two. Then names are shuffled into those slots.

Tips for using targets well

• Set a target for mains when the potluck is a real meal. Mains are the category most likely to fall short.
• Leave desserts and appetizers without targets, since they tend to get covered anyway.
• Turn off drinks if the host is covering them, rather than setting a target of zero.
• If your targets add up to more than your guest count, the tool still produces a fair result, but some targets will not be met. Lower them or add names.

Want help choosing numbers? The portion guide suggests rough proportions for a balanced table.

Last updated October 10, 2026.