ABMasonry

A lightweight, dependency-free Masonry-style image gallery built with TypeScript and CSS. Automatically distributes images across columns to achieve balanced vertical spacing.

Features

• Responsive image layout using CSS Flexbox
• Lazy-loading support
• Dynamic column height balancing
• Full-screen overlay on image click
• Horizontal drag scroll on mobile
• Works with dynamic or external data

Installation

npm install ab-masonry

Usage

HTML

Create a container where the gallery will be mounted:

<div id="masonry"></div>

JavaScript

import { ABMasonry } from 'ab-masonry';

const items = [
  {
    img: 'https://picsum.photos/300/400?random=1',
    caption: 'Photo 1',
    link: 'https://example.com/photo1'
  },
  {
    img: 'https://picsum.photos/300/300?random=2',
    caption: 'Photo 2'
  }
];

const options = {
  columns: 3,
  gap: '16px',
  lazy: true,
  overlayZIndex: 2147483647
};

const masonry = await ABMasonry.create('#masonry', items, options);
// No need to call `render()`, it's handled automatically

Styles

ABMasonry does not inject styles automatically. You must explicitly import the CSS manually:

@import 'ab-masonry/dist/ab-masonry.css';

Options

| Option | Type | Default | Description | |-----------------|------------|--------------|----------------------------------------------| | columns | number | 3 | Number of columns | | gap | string | '16px' | Gap between items and columns | | lazy | boolean | false | Enables loading="lazy" | | overlayZIndex | number | 2147483647 | Z-index of the full-screen overlay | | title | string | `` | Image title (used as alt and overlay text) |

Styling

All styles are scoped to .ab-masonry. You can override them as needed:

.ab-masonry__item {
    border-radius: 4px;
    overflow: hidden;
}

Development

npm install
npm run dev

License

MIT © Andrés Bedoya