Features

Advanced Animations

Breathing, pulse, and float animations with customizable timing and intensity.

Morphing Effects

Dynamic size changes on hover and long press with smooth transitions.

Responsive Design

Automatic breakpoint handling with customizable column configurations.

Performance Optimized

Hardware acceleration, throttled resize events, and intersection observers.

Touch Support

Full touch interaction support with long press detection and gesture handling.

Theme System

Multiple built-in themes with easy customization and CSS custom properties.

Configuration

Explore the full range of HY Masonry configuration options. Each section provides live controls that update the preview in real-time, allowing you to see exactly how your settings affect the layout, animations, and styling. The preview area is now much larger to show the complete extent of your configuration.

Layout Configuration

4
16
20
6
0

Code Example

const config = {
   columns: 4,
   gap: 16,
   padding: 20,
   borderWidth: 0
 };

// Add items with different sizes
masonry.addItem({
  id: 'item1',
  size: '2x2',
  content: 'Large Item'
});

masonry.addItem({
  id: 'item2', 
  size: '1x2',
  content: 'Tall Item'
});

Animation Configuration

300
2000
1.0

Code Example

const config = {
  animation: true,
  animationDuration: 300,
  breathingEffect: true,
  breathingSpeed: 2000,
  reduceMotion: true
};

// Add animated items
masonry.addItem({
  id: 'animated-item',
  size: '1x1',
  content: 'Animated Content',
  animationType: 'breathing',
  animationDelay: 0
});

Morphing Configuration

500

Code Example

const config = {
  morphing: true,
  morphDuration: 500,
  hoverMorph: true,
  longPressMorph: true
};

// Morph an item programmatically
masonry.morphItem('item-id', '2x2', 500);

// Add item with morphing configuration
masonry.addItem({
  id: 'morphable-item',
  size: '1x1',
  content: 'Morphable Item',
  morphOnHover: true,
  morphSize: '2x2',
  morphDuration: 500
});

Responsive Configuration

columns gap
columns gap
columns gap

Code Example

const config = {
  responsive: true,
  breakpoints: {
    mobile: { 
      minWidth: 0,
      maxWidth: 768,
      columns: 2, 
      gap: 12,
      padding: 16
    },
    tablet: { 
      minWidth: 769,
      maxWidth: 1024,
      columns: 3, 
      gap: 14,
      padding: 18
    },
    desktop: { 
      minWidth: 1025,
      maxWidth: null,
      columns: 4, 
      gap: 16,
      padding: 20
    }
  }
};

Interaction Configuration

500

Code Example

const config = {
  longPressDelay: 500,
  touchEnabled: true
};

Styling Configuration

8
1.0
1.02

Code Example

const config = {
  theme: 'default',
  borderRadius: 8,
     borderWidth: 0,
  shadow: true,
  backgroundColor: '#ffffff',
  textColor: '#000000',
  borderColor: '#e0e0e0',
  hoverScale: 1.02
};

// CSS Custom Properties
:root {
  --hy-masonry-gap: 16px;
--hy-masonry-padding: 20px;
--hy-masonry-border-radius: 8px;
--hy-masonry-border-width: 1px;
--hy-masonry-border-color: #333333;
--hy-masonry-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
--hy-masonry-transition: 300ms ease;
}

Performance Configuration

100

Code Example

const config = {
  throttleResize: 100,
  useTransform: true,
  hardwareAcceleration: true
};

Examples

Basic Layout

<hy-masonry></hy-masonry>

Animated Items

masonry.addItem({
  id: 'item1',
  size: '1x1',
  content: 'Animated Item',
  animationType: 'breathing'
});

Morphing Effects

masonry.morphItem('item1', '2x2', 500);

API Reference

Methods

addItem(item: MasonryItem)

Add a new item to the masonry layout.

masonry.addItem({
  id: 'unique-id',
  size: '1x1',
  content: 'Item content',
  backgroundColor: '#f0f0f0'
});

removeItem(itemId: string)

Remove an item from the masonry layout.

masonry.removeItem('item-id');

updateItem(itemId: string, newConfig: Partial<MasonryItem>)

Update an existing item's configuration.

masonry.updateItem('item-id', {
  size: '2x2',
  content: 'Updated content'
});

morphItem(itemId: string, newSize: string, duration?: number)

Morph an item to a new size with optional duration.

masonry.morphItem('item-id', '2x2', 500);

resetItem(itemId: string)

Reset an item to its original size.

masonry.resetItem('item-id');

updateConfig(newConfig: Partial<MasonryConfig>)

Update the masonry configuration.

masonry.updateConfig({
  columns: 6,
  gap: 20
});

Events

item:added

Fired when an item is added to the masonry.

item:removed

Fired when an item is removed from the masonry.

item:morphed

Fired when an item completes morphing.

layout:updated

Fired when the layout is recalculated.

Get Started

NPM

npm install hy-masonry

CDN

<script src="https://unpkg.com/hy-masonry@latest/dist/hy-masonry.js"></script>

GitHub

View on GitHub

Quick Start

<!DOCTYPE html>
<html>
<head>
    <script src="https://unpkg.com/hy-masonry@latest/dist/hy-masonry.js"></script>
</head>
<body>
    <hy-masonry id="masonry"></hy-masonry>
    
    <script>
        const masonry = document.getElementById('masonry');
        
        // Add items
        masonry.addItem({
            id: 'item1',
            size: '1x1',
            content: 'Hello World!',
            backgroundColor: '#f0f0f0'
        });
    </script>
</body>
</html>