Meowsonry

A lightweight, extensible masonry layout library for modern web applications. Built with TypeScript and inspired by middleware architecture patterns.

Features

• ✅ Intelligent row-based positioning - Optimizes vertical space across columns
• ✅ Middleware architecture - Extend and customize layout behavior
• ✅ Responsive design - Automatically adapts to container width changes
• ✅ Type-safe - Fully typed with strict TypeScript
• ✅ Zero dependencies - Pure JavaScript/TypeScript implementation
• ✅ Auto-update support - Built-in ResizeObserver integration
• ✅ First render flick prevention - Optional middleware for hiding unpositioned items and adding CSS animation hooks

Installation

npm install meowsonry-layout

Basic Usage

import { meowsonry } from "meowsonry-layout";

const container = document.querySelector(".masonry") as HTMLElement;

meowsonry({ container });

<div class="masonry">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Configuration

meowsonry({
  container: HTMLElement,
  middleware?: Middleware[]
});

Options

Option	Type	Description
container	HTMLElement	Container element (required)
middleware	Middleware[]	Array of custom middleware

Advanced Usage

With Gap Spacing

import { meowsonry, gap } from "meowsonry-layout";

const container = document.querySelector(".masonry") as HTMLElement;

meowsonry({
  container,
  middleware: [gap(16)], // 16px gap between items
});

With Auto-Update

import { meowsonry, autoUpdate } from "meowsonry-layout";

const container = document.querySelector(".masonry") as HTMLElement;

// Initialize layout and automatically update on resize
const cleanup = autoUpdate(container, () => {
  meowsonry({ container });
});

// Cleanup when no longer needed
cleanup();

Prevent First Render Flick

import { meowsonry, autoUpdate, gap, preventFlick } from "meowsonry-layout";

const container = document.querySelector(".masonry") as HTMLElement;

autoUpdate(container, () => {
  meowsonry({
    container,
    middleware: [preventFlick(), gap(16)],
  });
});

The preventFlick() middleware hides the container before the first layout is applied, reveals it after layout if it was initially hidden, and adds animation hooks to each item:

[data-meowsonry-prevent-flick] {
  animation: meowsonry-fade-in 220ms ease both;
  animation-delay: calc(var(--meowsonry-index) * 24ms);
}

@keyframes meowsonry-fade-in {
  from {
    opacity: 0;
    transform: translateY(12px);
  }

  to {
    opacity: 1;
    transform: translateY(0);
  }
}

Middleware System

Meowsonry uses a middleware pipeline architecture with three execution phases:

Type	When	Context
beforePlacement	Once before children	Container-level
placement	For each child	Child-specific
common	In both phases	Shared

Creating Custom Middleware

import { MIDDLEWARE_TYPE } from "meowsonry-layout";

const myMiddleware = {
  type: MIDDLEWARE_TYPE.placement,
  callback: ({ context, setContext }) => {
    // Access and modify context
    console.log("Processing child:", context.currentChildElement);

    // Update context with new values
    setContext((prev) => ({
      ...prev,
      customValue: "example",
    }));
  },
};

meowsonry({
  container,
  middleware: [myMiddleware],
});

See MIDDLEWARE.md for detailed documentation.

API Reference

meowsonry(options)

Main layout function that arranges child elements in a masonry grid.

function meowsonry({
  container: HTMLElement,
  middleware?: Middleware[]
}): void

autoUpdate(container, updateFn)

Sets up automatic updates using ResizeObserver.

function autoUpdate(container: HTMLElement, updateFn: () => void): () => void; // cleanup function

preventFlick()

Creates middleware that prevents first-render flicker and adds CSS hooks for custom appearance animations.

function preventFlick(): Middleware;

gap(value)

Creates middleware to add spacing between items.

function gap(value: number): BeforePlacementMiddleware;

Testing

Run unit tests:

npm test

Run e2e screenshot tests:

npm run test.playwright

Run e2e tests in UI mode:

npm run test.playwright.ui

Update screenshot snapshots:

npm run test.playwright.update

Type checking:

npm run typecheck

Linting:

npm run lint
npm run lint.fix

Architecture

Meowsonry uses a middleware pipeline architecture:

1. beforePlacement phase - Container initialization (executed once)
2. placement phase - Child element processing (executed per child)

This approach makes the library highly extensible while keeping the core logic clean and maintainable.

See ARCHITECTURE.md for detailed architecture documentation.

Contributing

See CODESTYLE.md for detailed coding standards.

See AGENTS.md for agents guidelines including:

• Code style and conventions
• Testing standards
• Commit message format
• Development workflow

License

MIT - See LICENSE for details.

Meow :3