rectpackr-layout

Rectpackr Layout

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

npm install rectpackr-layout

yarn

yarn add rectpackr-layout

pnpm

pnpm install rectpackr-layout

Then import it in your JavaScript:

// In your main.js or component file
import 'rectpackr-layout';

Or directly in your HTML:

<script type="module">
  import 'rectpackr-layout';
</script>

Using a CDN (No Build Step Needed)

Include it directly in your HTML via CDN:

unpkg

<script type="module" src="https://unpkg.com/rectpackr-layout"></script>

jsDelivr

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/rectpackr-layout"
></script>

esm.sh

<script type="module" src="https://esm.sh/rectpackr-layout"></script>

Once installed, use the web component anywhere in your HTML:

<rectpackr-layout>
  <div>Your content here</div>
</rectpackr-layout>

📖 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

<rectpackr-layout>
  <div>Card 1</div>
  <div>Card 2</div>
  <div>Card 3</div>
</rectpackr-layout>

<style>
  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%;
    }
  }
</style>

Dynamic Content Handling

<rectpackr-layout id="dynamic-layout">
  <!-- Content can be added/removed dynamically -->
</rectpackr-layout>

<script>
  // The layout automatically adjusts to content changes
  document.getElementById('dynamic-layout').appendChild(newElement);
</script>

🎯 Live Demos

Consistent Width Gallery

See predictable masonry-style layouts with equal-width elements

View on CodePen

Mixed Dimension Gallery

Explore optimal packing of variably-sized elements and aspect ratios

View on CodePen

Interactive Playground

Experiment with real-time controls and dynamic content manipulation

View on CodePen

✅ Browser Support

Modern browsers with Web Components support.

🔧 Issues and Support

If you encounter any issues or have questions, please open an issue.

📄 License

This project is licensed under the MIT License.