https://github.com/styiannis/rectpackr-layout
Web component that packs HTML elements as rectangles using best-fit 2D strip-packing algorithms. Automatically measures dimensions and handles mixed content.
https://github.com/styiannis/rectpackr-layout
best-fit custom-element custom-elements dom layout masonry masonry-layout rectangle-packer responsive responsive-layout strip-packing web-component web-components
Last synced: 5 months ago
JSON representation
Web component that packs HTML elements as rectangles using best-fit 2D strip-packing algorithms. Automatically measures dimensions and handles mixed content.
- Host: GitHub
- URL: https://github.com/styiannis/rectpackr-layout
- Owner: styiannis
- License: mit
- Created: 2025-09-23T23:12:15.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-03T16:14:36.000Z (9 months ago)
- Last Synced: 2025-10-03T18:30:50.999Z (9 months ago)
- Topics: best-fit, custom-element, custom-elements, dom, layout, masonry, masonry-layout, rectangle-packer, responsive, responsive-layout, strip-packing, web-component, web-components
- Language: TypeScript
- Homepage:
- Size: 33.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Rectpackr Layout
[](https://www.npmjs.com/package/rectpackr-layout)
[](https://coveralls.io/github/styiannis/rectpackr-layout?branch=main)
[](https://codepen.io/collection/dGpeLa)
A web component that creates layouts by treating your HTML elements as rectangles and packing them using a best-fit 2D strip-packing algorithm.
## ⚙️ Why a Packing Algorithm for Web Layouts?
Web browsers naturally manage elements as rectangles. `rectpackr-layout` leverages this by applying a best-fit strip-packing algorithm — the same approach used in industrial optimization problems — to web layout creation.
## 🤖 Layouts Through Automated Measurement
The algorithm intelligently works with whatever dimensional information is available:
### How It Works:
- **Automatically measures** element dimensions through browser APIs
- **Uses width as the primary constraint** for predictable flow
- **Adapts to any height** — whether fixed, aspect-ratio based, or content-determined
- **Handles mixed content seamlessly** without manual configuration
### You Can:
- Set explicit widths for pixel-perfect control
- Use percentage-based or responsive widths
- Let elements determine their own natural sizes
- Mix and match approaches within the same layout
### What This Enables:
- **Truly flexible layouts** that work with your existing CSS approach
- **Zero-configuration setups** for rapid prototyping
- **Production-ready precision** when you need exact control
- **Best of both worlds** — automation when you want it, control when you need it
## 📥 Installation
### Install the package via your preferred package manager:
#### npm
```bash
npm install rectpackr-layout
```
#### yarn
```bash
yarn add rectpackr-layout
```
#### pnpm
```bash
pnpm install rectpackr-layout
```
Then import it in your JavaScript:
```javascript
// In your main.js or component file
import 'rectpackr-layout';
```
Or directly in your HTML:
```html
import 'rectpackr-layout';
```
### Using a CDN (No Build Step Needed)
Include it directly in your HTML via CDN:
#### unpkg
```html
```
#### jsDelivr
```html
```
#### esm.sh
```html
```
### Once installed, use the web component anywhere in your HTML:
```html
Your content here
```
## 📖 API Reference
### Attributes
**`positioning`**
Defines the CSS method used to position items.
- `transform` (_Default_): Uses `transform: translate(x, y)`
- `offset`: Uses CSS `inset` property for precise positioning
> 💡 **Performance Note:** The default `transform` value typically offers better performance through hardware acceleration. Use `offset` only when child elements already use `transform` for other purposes (animation etc.).
**`x-direction`**
Controls the horizontal packing direction.
- `ltr` (_Default_): Left-to-right packing
- `rtl`: Right-to-left packing
**`y-direction`**
Controls the vertical packing direction.
- `ttb` (_Default_): Top-to-bottom packing
- `btt`: Bottom-to-top packing
### A Note on Visual Order & Accessibility
The `x-direction` and `y-direction` attributes control visual placement, which may create a difference between the visual arrangement and the underlying DOM order.
- **DOM Order is Preserved:** The underlying HTML structure remains unchanged
- **Visual Order is Algorithm-Determined**: Item placement follows the packing logic and your direction settings
## 🚀 Usage Examples
### Fluid, Responsive Layout
```html
Card 1
Card 2
Card 3
rectpackr-layout {
container-type: inline-size;
display: block;
}
rectpackr-layout > * {
/* Fluid width based on container queries */
width: 100%;
}
@container (min-width: 400px) {
rectpackr-layout > * {
width: 50%;
}
}
@container (min-width: 800px) {
rectpackr-layout > * {
width: 33.33%;
}
}
```
### Dynamic Content Handling
```html
// The layout automatically adjusts to content changes
document.getElementById('dynamic-layout').appendChild(newElement);
```
## 🎯 Live Demos
### Consistent Width Gallery
See predictable masonry-style layouts with equal-width elements
[View on CodePen](https://codepen.io/styiannis/pen/ogbzBXg)
### Mixed Dimension Gallery
Explore optimal packing of variably-sized elements and aspect ratios
[View on CodePen](https://codepen.io/styiannis/pen/XJXjayR)
### Interactive Playground
Experiment with real-time controls and dynamic content manipulation
[View on CodePen](https://codepen.io/styiannis/pen/qEbqMBZ)
## ✅ Browser Support
Modern browsers with Web Components support.
## 🔧 Issues and Support
If you encounter any issues or have questions, please [open an issue](https://github.com/styiannis/rectpackr-layout/issues).
## 📄 License
This project is licensed under the [MIT License](https://github.com/styiannis/rectpackr-layout?tab=MIT-1-ov-file#readme).