⚡

Layouts Masonry,
simples y elegantes

Crea layouts tipo Pinterest con CSS Grid. Ligero, responsivo y sin dependencias. Perfecto para galerías de imágenes, portfolios y más.

Comenzar Ver en GitHub

~2KB

Tamaño minificado

Zero

Dependencias

100%

CSS Grid

Responsive

Por diseño

Características principales

Todo lo que necesitas para crear layouts masonry profesionales

⚡

Zero Dependencias

Puro JavaScript vanilla. Sin jQuery, sin frameworks. Solo añade el script y listo.

📱

Totalmente Responsive

Define breakpoints personalizados. Diferentes columnas para cada tamaño de pantalla.

🎨

CSS Grid Nativo

Aprovecha el poder de CSS Grid. Rendimiento óptimo con tecnología nativa del navegador.

⚙️

Fácil Configuración

Configuración simple e intuitiva. Opciones por defecto que funcionan de inmediato.

🎯

Variables CSS

Personaliza espaciados con variables CSS. Cambia gaps entre columnas e items fácilmente.

🔄

Resize Inteligente

Debounce configurable para resize. Mejor rendimiento sin sacrificar la experiencia.

📡

Callbacks Útiles

Eventos init y afterBreakpoint. Controla el comportamiento en cada cambio.

🚀

Ligero y Rápido

Menos de 2KB minificado. Carga instantánea y ejecución ultra rápida.

🌐

Amplio Soporte

Compatible con todos los navegadores modernos. Chrome 57+, Firefox 52+, Safari 10.1+.

Demo Interactivo

Mira Light Masonry en acción. Cambia el tamaño de tu navegador para ver cómo se adapta.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Ver más ejemplos en CodePen

Instalación

Elige el método que prefieras para integrar Light Masonry en tu proyecto

NPM

Terminal

npm install light-masonry

JavaScript - ES Modules

import LightMasonry from 'light-masonry';

JavaScript - CommonJS

const LightMasonry = require('light-masonry');

CDN

unpkg:

HTML

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/light-masonry/light-masonry.min.css">

<!-- JavaScript -->
<script src="https://unpkg.com/light-masonry/light-masonry.min.js"></script>

jsDelivr:

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/light-masonry/light-masonry.min.css">
<script src="https://cdn.jsdelivr.net/npm/light-masonry/light-masonry.min.js"></script>

Inicio Rápido

Tres simples pasos para tener tu layout masonry funcionando

1. Estructura HTML

Crea un contenedor con los elementos que quieres organizar:

HTML

<div class="masonry-container">
  <div class="masonry-item">Item 1</div>
  <div class="masonry-item">Item 2</div>
  <div class="masonry-item">Item 3</div>
  <div class="masonry-item">Item 4</div>
  <!-- Más items... -->
</div>

2. Incluir CSS

Importa los estilos necesarios:

CSS - Import

@import "light-masonry/light-masonry.min.css";

O usa un tag <link>:

HTML - Link

<link rel="stylesheet" href="path/to/light-masonry.min.css">

3. Inicializar JavaScript

Crea una nueva instancia de Light Masonry:

JavaScript

// Selecciona el contenedor
const container = document.querySelector('.masonry-container');

// Inicializa Light Masonry
const masonry = new LightMasonry(container, {
  defaultColumns: 4,
  responsive: {
    1440: 4,
    1024: 3,
    768: 2,
    480: 1
  }
});

¡Listo!

Tu layout masonry está funcionando. Los items se distribuirán automáticamente en columnas y se adaptarán al cambiar el tamaño de la ventana.

API Reference

Documentación completa de opciones y configuración

Constructor

JavaScript

new LightMasonry(element, options)

Parámetros

Parámetro	Tipo	Descripción
`element`	HTMLElement	El contenedor del layout masonry (requerido)
`options`	Object	Objeto de configuración (opcional)

Opciones

Opción	Tipo	Por Defecto	Descripción
`defaultColumns`	Number	`4`	Número de columnas cuando no hay breakpoints activos
`resizeDelay`	Number	`0`	Delay en ms para debounce del resize (0 = sin debounce)
`responsive`	Object	`{}`	Breakpoints y columnas (desktop-first)
`init`	Function	`() => {}`	Callback ejecutado al inicializar
`afterBreakpoint`	Function	`() => {}`	Callback ejecutado al cambiar de breakpoint

defaultColumns

Define el número de columnas por defecto cuando el viewport es mayor que todos los breakpoints definidos.

JavaScript

new LightMasonry(container, {
  defaultColumns: 5 // 5 columnas por defecto
});

resizeDelay

Activa el debounce para el evento resize. Mejora el rendimiento esperando a que el usuario termine de redimensionar.

JavaScript

new LightMasonry(container, {
  resizeDelay: 250 // Espera 250ms después del último resize
});

Valores recomendados:
• 0: Sin debounce (respuesta instantánea)
• 150-250: Balance entre rendimiento y respuesta
• 300-500: Mejor rendimiento, ligero delay

responsive

Define breakpoints y el número de columnas para cada uno. Usa un enfoque desktop-first: cuando el ancho del viewport es menor o igual al breakpoint, se aplica ese número de columnas.

JavaScript

new LightMasonry(container, {
  responsive: {
    1440: 4, // 4 columnas cuando width <= 1440px
    1024: 3, // 3 columnas cuando width <= 1024px
    768: 2,  // 2 columnas cuando width <= 768px
    480: 1   // 1 columna cuando width <= 480px
  }
});

Callbacks

Ambos callbacks reciben un objeto data con información del estado actual:

Propiedad	Tipo	Descripción
`columns`	Number	Número actual de columnas
`breakpoint`	Number \| String	Breakpoint activo o 'defaultColumns'

JavaScript

new LightMasonry(container, {
  init: (data) => {
    console.log('Inicializado con', data.columns, 'columnas');
    console.log('Breakpoint:', data.breakpoint);
  },
  afterBreakpoint: (data) => {
    console.log('Cambiado a', data.columns, 'columnas');

    // Ejemplo: activar animaciones en mobile
    if (data.columns === 1) {
      console.log('Vista móvil activada');
    }
  }
});

Ejemplos de Uso

Casos de uso comunes y configuraciones típicas

Uso Básico

Configuración mínima para empezar rápidamente:

JavaScript

const masonry = new LightMasonry(
  document.querySelector('.masonry-container')
);

Responsive Completo

Layout completamente adaptable con callbacks:

JavaScript

const masonry = new LightMasonry(
  document.querySelector('.masonry-container'),
  {
    defaultColumns: 4,
    responsive: {
      1440: 4,
      1024: 3,
      768: 2,
      480: 1
    },
    resizeDelay: 200,
    init: (data) => {
      console.log(`Inicializado con ${data.columns} columnas`);
    },
    afterBreakpoint: (data) => {
      console.log(`Ahora mostrando ${data.columns} columnas`);
    }
  }
);

Galería de Imágenes

HTML y JavaScript para una galería tipo Pinterest:

HTML

<div class="gallery">
  <div class="gallery-item">
    <img src="image1.jpg" alt="Imagen 1">
    <h3>Título 1</h3>
    <p>Descripción...</p>
  </div>
  <div class="gallery-item">
    <img src="image2.jpg" alt="Imagen 2">
    <h3>Título 2</h3>
    <p>Descripción...</p>
  </div>
  <!-- Más items... -->
</div>

CSS

.gallery {
  --gap: 20px;
  --gap-between-columns: 30px;
  --gap-between-items: 20px;
  padding: 20px;
}

.gallery-item {
  background: #f5f5f5;
  border-radius: 8px;
  overflow: hidden;
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
  transition: transform 0.3s;
}

.gallery-item:hover {
  transform: translateY(-5px);
}

.gallery-item img {
  width: 100%;
  display: block;
}

.gallery-item h3 {
  padding: 15px 15px 5px;
  margin: 0;
}

.gallery-item p {
  padding: 0 15px 15px;
  margin: 0;
  color: #666;
}

JavaScript

const gallery = new LightMasonry(
  document.querySelector('.gallery'),
  {
    defaultColumns: 4,
    responsive: {
      1200: 4,
      900: 3,
      600: 2,
      400: 1
    },
    resizeDelay: 150
  }
);

Contenido Dinámico

Cargar más items y reinicializar el layout:

JavaScript

const container = document.querySelector('.masonry-container');
let masonry = new LightMasonry(container, {
  defaultColumns: 4,
  responsive: { 1024: 3, 768: 2, 480: 1 }
});

// Función para cargar más items
function loadMoreItems() {
  fetch('/api/items')
    .then(response => response.json())
    .then(items => {
      // Añadir nuevos items al DOM
      items.forEach(item => {
        const div = document.createElement('div');
        div.className = 'masonry-item';
        div.innerHTML = item.content;
        container.appendChild(div);
      });

      // Reinicializar para incluir los nuevos items
      masonry = new LightMasonry(container, {
        defaultColumns: 4,
        responsive: { 1024: 3, 768: 2, 480: 1 }
      });
    });
}

// Llamar cuando el usuario hace scroll al final
window.addEventListener('scroll', () => {
  if ((window.innerHeight + window.scrollY) >= document.body.offsetHeight) {
    loadMoreItems();
  }
});

Variables CSS

Personaliza los espaciados usando variables CSS

Light Masonry utiliza variables CSS personalizadas para controlar los espaciados. Puedes modificarlas directamente en tu CSS:

CSS

.masonry-container {
  /* General gap (aplica a columnas e items) */
  --gap: 20px;

  /* Gap horizontal entre columnas */
  --gap-between-columns: var(--gap);

  /* Gap vertical entre items */
  --gap-between-items: var(--gap);
}

Variables Disponibles

Variable	Por Defecto	Descripción
`--gap`	`5px`	Espaciado general para columnas e items
`--gap-between-columns`	`var(--gap)`	Espaciado horizontal entre columnas
`--gap-between-items`	`var(--gap)`	Espaciado vertical entre items

Ejemplo de Personalización

CSS

/* Diferentes espaciados para diferentes tamaños */
.masonry-container {
  --gap: 30px;
  --gap-between-columns: 40px;
  --gap-between-items: 20px;
}

/* Reducir gaps en móvil */
@media (max-width: 768px) {
  .masonry-container {
    --gap: 15px;
    --gap-between-columns: 15px;
    --gap-between-items: 15px;
  }
}

Layouts Masonry, simples y elegantes

Características principales

Zero Dependencias

Totalmente Responsive

CSS Grid Nativo

Fácil Configuración

Variables CSS

Resize Inteligente

Callbacks Útiles

Ligero y Rápido

Amplio Soporte

Demo Interactivo

Instalación

NPM

CDN

Inicio Rápido

1. Estructura HTML

2. Incluir CSS

3. Inicializar JavaScript

¡Listo!

API Reference

Constructor

Parámetros

Opciones

defaultColumns

resizeDelay

responsive

Callbacks

Ejemplos de Uso

Uso Básico

Responsive Completo

Galería de Imágenes

Contenido Dinámico

Variables CSS

Variables Disponibles

Ejemplo de Personalización

Layouts Masonry,
simples y elegantes