# metafizzy/packery architecture

> Architecture diagram of the GitHub repository metafizzy/packery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metafizzy/packery
- Repository: https://github.com/metafizzy/packery

## Overview

Packery is a browser bin-packing layout library. An application initializes Packery on a DOM container, after which the layout controller measures items, packs their rectangles, and positions them in the container. Optional draggable integrations feed movement events back into Packery, which computes drop targets and relays the final placement. The excerpts directly support the core layout, geometry, item lifecycle, stamping, resizing, and drag flow; declarative and jQuery entry behavior is represented through the documented/demo integrations.

Main entry points: [`js/packery.js`](https://github.com/metafizzy/packery/blob/master/js/packery.js) (Packery Controller), [`js/item.js`](https://github.com/metafizzy/packery/blob/master/js/item.js) (Packery Item), [`js/rect.js`](https://github.com/metafizzy/packery/blob/master/js/rect.js) (Rectangle Geometry), [`sandbox/browserify/jquery-main.js`](https://github.com/metafizzy/packery/blob/master/sandbox/browserify/jquery-main.js) (jQuery Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Layout API"]
  node_jquery_bridge["jQuery Bridge<br/>[jquery-main.js]"]
  node_packery["Packery Controller<br/>[packery.js]"]
  node_outlayer["Outlayer Runtime"]
end

subgraph group_packing["Packing Engine"]
  node_packer["Bin Packer<br/>[packer.js]"]
  node_rect["Rectangle Geometry<br/>[rect.js]"]
end

subgraph group_items["Item Lifecycle"]
  node_item["Packery Item<br/>[item.js]"]
  node_size_measurement["Size Measurement"]
end

subgraph group_interaction["Drag Interaction"]
  node_drag_source["Drag Source"]
  node_shift_packer["Drop Packer<br/>[packery.js]"]
  node_placeholder["Drop Placeholder<br/>[item.js]"]
end

node_application(("Application"))
node_dom[("DOM Container")]
node_jquery_ui["jQuery UI Draggable"]

node_application -->|"initializes"| node_packery
node_application -.->|"registers plugin"| node_jquery_bridge
node_jquery_bridge -.->|"invokes API"| node_packery
node_packery -->|"lays out items"| node_dom
node_packery -->|"creates layout"| node_outlayer
node_packery -->|"manages items"| node_item
node_packery -->|"measures elements"| node_size_measurement
node_packery -->|"packs rectangles"| node_packer
node_packery -->|"creates rectangles"| node_rect
node_item -->|"extends item"| node_outlayer
node_item -->|"stores geometry"| node_rect
node_size_measurement -->|"reads dimensions"| node_dom
node_packer -->|"updates spaces"| node_rect
node_drag_source -->|"sends drag events"| node_packery
node_jquery_ui -.->|"provides events"| node_drag_source
node_packery -->|"computes drop targets"| node_shift_packer
node_shift_packer -->|"packs targets"| node_rect
node_packery -->|"positions placeholder"| node_placeholder
node_placeholder -->|"renders feedback"| node_dom
node_packery -->|"positions items"| node_item

click node_jquery_bridge "https://github.com/metafizzy/packery/blob/master/sandbox/browserify/jquery-main.js"
click node_packery "https://github.com/metafizzy/packery/blob/master/js/packery.js"
click node_item "https://github.com/metafizzy/packery/blob/master/js/item.js"
click node_packer "https://github.com/metafizzy/packery/blob/master/js/packer.js"
click node_rect "https://github.com/metafizzy/packery/blob/master/js/rect.js"
click node_shift_packer "https://github.com/metafizzy/packery/blob/master/js/packery.js"
click node_placeholder "https://github.com/metafizzy/packery/blob/master/js/item.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_jquery_bridge,node_packery,node_outlayer,node_jquery_ui toneBlue
class node_packer,node_rect,node_dom toneAmber
class node_item,node_size_measurement toneMint
class node_drag_source,node_shift_packer,node_placeholder toneRose
class node_application toneIndigo
```

## Components

### Layout API

- [jQuery Bridge](https://github.com/metafizzy/packery/blob/master/sandbox/browserify/jquery-main.js): `sandbox/browserify/jquery-main.js`
- [Packery Controller](https://github.com/metafizzy/packery/blob/master/js/packery.js): `js/packery.js`
- **Outlayer Runtime**

### Packing Engine

- [Bin Packer](https://github.com/metafizzy/packery/blob/master/js/packer.js): `js/packer.js`
- [Rectangle Geometry](https://github.com/metafizzy/packery/blob/master/js/rect.js): `js/rect.js`

### Item Lifecycle

- [Packery Item](https://github.com/metafizzy/packery/blob/master/js/item.js): `js/item.js`
- **Size Measurement**

### Drag Interaction

- **Drag Source**
- [Drop Packer](https://github.com/metafizzy/packery/blob/master/js/packery.js): `js/packery.js`
- [Drop Placeholder](https://github.com/metafizzy/packery/blob/master/js/item.js): `js/item.js`

### Other components

- **Application**
- **DOM Container**
- **jQuery UI Draggable**

## Connections

- Application → Packery Controller: initializes
- Application → jQuery Bridge: registers plugin
- jQuery Bridge → Packery Controller: invokes API
- Packery Controller → DOM Container: lays out items
- Packery Controller → Outlayer Runtime: creates layout
- Packery Controller → Packery Item: manages items
- Packery Controller → Size Measurement: measures elements
- Packery Controller → Bin Packer: packs rectangles
- Packery Controller → Rectangle Geometry: creates rectangles
- Packery Item → Outlayer Runtime: extends item
- Packery Item → Rectangle Geometry: stores geometry
- Size Measurement → DOM Container: reads dimensions
- Bin Packer → Rectangle Geometry: updates spaces
- Drag Source → Packery Controller: sends drag events
- jQuery UI Draggable → Drag Source: provides events
- Packery Controller → Drop Packer: computes drop targets
- Drop Packer → Rectangle Geometry: packs targets
- Packery Controller → Drop Placeholder: positions placeholder
- Drop Placeholder → DOM Container: renders feedback
- Packery Controller → Packery Item: positions items
