binpackingjs

A fast, fully-typed 2D and 3D bin packing library for JavaScript and TypeScript.

• Immutable — input objects are never mutated; results are returned as new objects
• Tree-shakeable — import only binpackingjs/2d or binpackingjs/3d to keep your bundle small
• Zero runtime dependencies
• ESM + CJS — works everywhere: Node.js, Bun, Deno, browsers (via bundler)

Algorithm references

• 2D: A Thousand Ways to Pack the Bin (Jukka Jylänki) — maximal rectangles with pluggable heuristics
• 3D: Optimizing Three-Dimensional Bin Packing Through Simulation (Erick Dube et al.) — pivot-based placement with rotation scoring

Playground

Playground contributed by @seanparkross — thank you!

Live interactive demos of every feature in this README — pack2D / pack3D, all four heuristics, rotation control, and a 3D viewer — at olragon.github.io/binpackingjs.

Run it locally:

bun install
bun run playground:dev   # http://localhost:3031

Or build a static bundle for hosting:

bun run playground:build # outputs to playground/dist

The playground is auto-deployed to GitHub Pages on every push to master via .github/workflows/playground.yml. To enable on a fresh fork: repo Settings → Pages → Source: GitHub Actions.

Install

npm install binpackingjs
# or
bun add binpackingjs
# or
yarn add binpackingjs

Quick Start

2D Bin Packing

import { pack2D } from 'binpackingjs/2d';

const result = pack2D({
  bins: [
    { width: 100, height: 50 },
    { width: 50, height: 50 },
  ],
  boxes: [
    { width: 15, height: 10 },
    { width: 50, height: 45 },
    { width: 40, height: 40 },
    { width: 200, height: 200 }, // Too large to fit
  ],
});

console.log(result.packedBins[0].boxes);
// [
//   { width: 40, height: 40, x: 0, y: 0, rotated: false, sourceBox: ... },
//   { width: 15, height: 10, x: 0, y: 40, rotated: false, sourceBox: ... },
// ]

console.log(result.packedBins[1].boxes);
// [
//   { width: 50, height: 45, x: 0, y: 0, rotated: false, sourceBox: ... },
// ]

console.log(result.unpackedBoxes.length); // 1 (the 200x200 box)

3D Bin Packing

import { pack3D } from 'binpackingjs/3d';

const result = pack3D({
  bins: [
    { name: 'Small Box', width: 296, height: 296, depth: 8, maxWeight: 1000 },
  ],
  items: [
    { name: 'Item 1', width: 250, height: 250, depth: 2, weight: 200 },
    { name: 'Item 2', width: 250, height: 250, depth: 2, weight: 200 },
    { name: 'Item 3', width: 250, height: 250, depth: 2, weight: 200 },
  ],
});

console.log(result.packedBins[0].items.length); // 3
console.log(result.unfitItems.length);          // 0

API Reference

pack2D(options): Pack2DResult

Option	Type	Default	Description
bins	Bin2D[]	required	Available bins { width, height }
boxes	Box2D[]	required	Boxes to pack { width, height, constrainRotation? }
heuristic	Heuristic	BestShortSideFit	Placement strategy
limit	number	all	Max boxes to pack

Returns { packedBins: PackedBin2D[], unpackedBoxes: Box2D[] }

Each PackedBin2D contains:

• boxes — packed boxes with x, y, width, height, rotated, and sourceBox (reference to input)
• efficiency — percentage of bin area used

pack3D(options): Pack3DResult

Option	Type	Default	Description
bins	Bin3D[]	required	Available bins { name, width, height, depth, maxWeight }
items	Item3D[]	required	Items to pack { name, width, height, depth, weight, allowedRotations? }

Returns { packedBins: PackedBin3D[], unfitItems: Item3D[] }

Each PackedItem3D contains position, rotationType, dimension, and sourceItem (reference to input).

Heuristics (2D)

import { pack2D, BestAreaFit } from 'binpackingjs/2d';

const result = pack2D({
  bins: [{ width: 100, height: 50 }],
  boxes: [{ width: 50, height: 100 }],
  heuristic: new BestAreaFit(),
});

Heuristic	Description
BestShortSideFit	(default) Minimizes leftover on the shorter side
BestAreaFit	Minimizes wasted area in the chosen free rectangle
BestLongSideFit	Minimizes leftover on the longer side
BottomLeft	Places items as low and left as possible

Rotation Control

2D — Constrain rotation

pack2D({
  bins: [{ width: 100, height: 50 }],
  boxes: [
    { width: 50, height: 100, constrainRotation: true }, // Will NOT be rotated to fit
  ],
});

3D — Restrict allowed rotations

import { pack3D, RotationType } from 'binpackingjs/3d';

pack3D({
  bins: [{ name: 'Bin', width: 100, height: 100, depth: 300, maxWeight: 1500 }],
  items: [{
    name: 'Fragile Item',
    width: 150, height: 50, depth: 50, weight: 20,
    allowedRotations: [RotationType.WHD, RotationType.DHW], // Only 2 of 6 rotations
  }],
});

All 6 rotation types: WHD, HWD, HDW, DHW, DWH, WDH.

Class-based API

For a more imperative style:

import { Packer2D } from 'binpackingjs/2d';
import { Packer3D } from 'binpackingjs/3d';

// 2D
const packer2d = new Packer2D([{ width: 100, height: 50 }]);
const result2d = packer2d.pack([{ width: 50, height: 50 }]);

// 3D
const packer3d = new Packer3D();
packer3d.addBin({ name: 'Bin', width: 100, height: 100, depth: 100, maxWeight: 1000 });
packer3d.addItem({ name: 'Item', width: 50, height: 50, depth: 50, weight: 10 });
const result3d = packer3d.pack();

Migrating from v3

v4 is a full rewrite. Key changes:

v3	v4
new Box(w, h) then check box.packed, box.x, box.y	Pass plain objects; read placement from result
bin.boxes mutated in place	result.packedBins[i].boxes on the return value
require('binpackingjs').BP2D	import { pack2D } from 'binpackingjs/2d'
new Packer(bins).pack(boxes) returns packed boxes	pack2D({ bins, boxes }) returns full result
packer.addBin() / packer.addItem() / packer.pack() (void)	packer.pack() returns Pack3DResult
packer.unfitItems after pack	result.unfitItems on the return value

License

MIT