What happens to your photo
The file is turned into a local object URL and handed to an <img> element, which the browser decodes with the same code path it uses for any image on any web page. It is then drawn onto an off-screen canvas, scaled so its longest side is 150 pixels — a 4000×3000 photo becomes 150×113, about seventeen thousand pixels. Every pixel more transparent than half opacity is discarded, and the rest go into the quantizer as plain RGB triples. There is no upload, no network request and no temporary file: close the tab and the canvas is gone with it.
Median cut then runs. All the pixels start in one bucket. Each round, the tool finds the bucket whose red, green or blue values span the widest range, sorts that bucket along the offending channel, and splits it in half at the median — so the bucket holding the most colour variation is always the next one divided. Repeat until you have as many buckets as swatches requested. Each bucket becomes one swatch, coloured by the arithmetic mean of its pixels, and the list is ordered by how many pixels each bucket ended up holding. The percentage under each swatch is that bucket's share of the sampled pixels.
One deliberate detail: a bucket with zero colour variation is never chosen for splitting. Without that rule, a poster-style image containing only three colours asked for eight swatches would return the same colours several times over. Instead the tool stops at however many distinct groups the image actually has.
Where the algorithm misleads you
Median cut counts pixels, not importance. It has no idea what the photograph is of. A landscape that is 70% sky will spend most of its splits subdividing near-identical blues, and a small red jacket that your eye goes to first can end up folded into a neighbouring bucket and never appear. If the palette misses the thing you care about, that is the mechanism — not a bug.
Averaging can invent a colour that is not in the image. Each swatch is the mean of its bucket, so a bucket that still contains both warm reds and cool greens resolves to a muddy olive that appears nowhere in the original. This is most visible at low swatch counts on busy images; raising the count from 4 to 6 usually resolves it, because the offending bucket gets split.
The 150-pixel downscale runs before anything else. The browser smooths as it scales, which blends neighbouring pixels together — so a thin, high-contrast detail like a logo, a line of coloured text or a narrow stripe is averaged into its surroundings before the quantizer ever sees it. That is the trade for making the whole thing instant, but it means the tool describes broad colour regions, not fine detail.
Format support is the browser's, not the file picker's. Anything your browser can decode works — JPEG, PNG, WebP, GIF, BMP and, on current browsers, AVIF. HEIC is the common failure: iPhone photos in their native format decode on Apple platforms but not in Chrome or Firefox on Windows and Android, where the image simply never loads. Run those through the HEIC to JPG converter first.
Getting a palette you can actually use
Crop first, extract second. Because the result is driven purely by area, framing is the control you have over it — cropping to the subject before dropping the file in is far more effective than changing the swatch count afterwards. The image cropper does this in the browser too, so nothing is uploaded at either step.
Five or six swatches is the useful range for most photographs. Four tends to over-merge; eight usually spends the extra two on further subdivisions of whatever already dominated, which is why the eighth swatch is so often a near-duplicate of the seventh. If two swatches come back looking identical, that is the honest answer — the image does not contain a distinct eighth colour region.
Treat the output as raw material rather than a finished palette. The most common mistake is to take the top swatch by percentage and make it the brand colour; in most photographs the largest region is the background, the sky or the wall. Pick the swatch that carries the subject, then build tints, shades and harmonies around it in the colour palette generator, which gives you the full lightness ramp a real interface needs. The Copy CSS button here writes the swatches out as custom properties in dominance order, ready to rename.
What to expect from different images
| Image type | Typical result | What helps |
|---|
| Portrait on a plain backdrop | Backdrop and skin tones dominate; clothing colours appear only if they occupy real area. | Crop tight to the subject. |
| Landscape with a large sky | Several near-identical blues, with ground colours compressed into one or two swatches. | Crop out most of the sky, or raise the count to 8. |
| Product shot on white | The first swatch is white or near-white and carries a very high percentage. | Crop to the product; ignore the top swatch. |
| Flat illustration or screenshot | Accurate and stable — flat colour regions are exactly what median cut handles best. | Nothing; this is the ideal case. |
| PNG with transparency | Transparent areas are skipped entirely, so percentages describe only the visible pixels. | Nothing — this is usually what you want. |
| Photo with one small bright accent | The accent is often absorbed into a larger bucket and missing from the palette. | Crop to it, or use the colour picker to sample that pixel directly. |