User guide

maxrects-packer aims to pack rectangles into as few normal bins as possible within a maximum width × height — sprite sheets, texture atlases and any other "many small images into few big images" problem. A rect that cannot fit gets an oversized placeholder bin of its own.

It differs from most packing libraries by what it optimizes: instead of making one output image of minimum size, it aims for a small number of images under a maximum size — a heuristic target, not a guarantee (what the algorithm guarantees). A single 8192×8192 atlas is not browser-friendly, while four 1024×1024 sheets usually are.

• Getting started — install and a runnable example.
• Options — every constructor argument and option, with defaults.
• Packing — adding rects, what a bin holds, oversized rects, packing logic.
• Rotation and tags — 90° rotation and tag-based grouping.
• Repacking — the dirty flag and repack().
• Persistence — save() and load().
• Upgrading to 3.0 — what a 2.x consumer has to change, and why.
• Troubleshooting — the sharp edges, and what the library does not do.

The API reference is generated from the source and its JSDoc: API.

Packing is a heuristic, not a solver — see packing for what that means in practice.