Hequalizer Logo

Iguala alturas perfectamente,
sin complicaciones

Librería JavaScript ligera que iguala automáticamente las alturas de elementos DOM mediante variables CSS. Perfecta para carousels, grids y layouts responsivos.

Comenzar Ver en GitHub
npm version license bundle size
~2KB
Tamaño minificado
Zero
Dependencias
Auto
Recalculación
100%
Vanilla JS

Características principales

Todo lo que necesitas para igualar alturas de forma automática y eficiente

🎯

Igualación Automática

Calcula y aplica la altura máxima mediante variables CSS personalizables sin intervención manual.

📱

Sistema Responsive

Breakpoints configurables con opciones específicas por viewport para control total en cada dispositivo.

🔄

Actualización Automática

MutationObserver y eventos de resize mantienen las alturas sincronizadas automáticamente.

🎨

Modos de Columnas

Iguala todos los elementos o agrúpalos por número de columnas según tus necesidades de layout.

⚡

Lifecycle Hooks

Eventos en cada etapa del ciclo de vida para debugging y control avanzado de la funcionalidad.

🌐

Framework Agnostic

Compatible con React, Vue, Angular, Svelte y cualquier framework moderno o vanilla JS.

Instalación

NPM

Terminal 
npm install hequalizer
JavaScript 
// ES modules
import Hequalizer from 'hequalizer';

// CommonJS
const Hequalizer = require('hequalizer');

CDN

HTML 
<script src="https://cdn.jsdelivr.net/npm/hequalizer@1.0.0/hequalizer.min.js"></script>

Uso Básico

HTML

index.html 
<div class="card-container">
  <div class="card">
    <h3>Título 1</h3>
    <p>Contenido variable...</p>
  </div>
  <div class="card">
    <h3>Título 2</h3>
    <p>Contenido con diferente altura...</p>
  </div>
  <div class="card">
    <h3>Título 3</h3>
    <p>Más contenido...</p>
  </div>
</div>

JavaScript

app.js 
// Seleccionar los títulos de las tarjetas
const cardTitles = document.querySelectorAll('.card h3');

// Inicializar Hequalizer
new Hequalizer(cardTitles);

CSS

styles.css 
/* La variable CSS --height se aplica automáticamente */
.card h3 {
  height: var(--height);
}
Hequalizer recalcula las alturas cuando:
  • El DOM esté completamente cargado (DOMContentLoaded)
  • El contenido cambie (mediante MutationObserver)
  • La ventana cambie de tamaño (resize event)

Configuración

Sintaxis 
new Hequalizer(elements, options)
Opción Tipo Default Descripción
cssVariable String '--height' Nombre de la variable CSS
columns String | Number 'all' Modo de columnas: "all" o número
initialIndex Number 0 Índice desde donde iniciar
resizeObserver Boolean true Activar MutationObserver
classElementToOmit String '' Clase para omitir elementos
on Object {} Lifecycle hooks
responsive Object {} Breakpoints responsive

API

Métodos de Instancia

JavaScript 
const instance = new Hequalizer(elements);

// Actualizar manualmente
instance.update();

// Reinicializar
instance.init();

// Destruir (mantener en registro)
instance.destroy();

// Destruir y remover del registro
instance.destroy(true);

Propiedades de Instancia

JavaScript 
instance.id               // ID único generado
instance.elementsArray    // Elementos originales
instance.values           // Altura(s) calculada(s)
instance.actualOptions    // Opciones aplicadas
instance.actualBreakpoint // Breakpoint actual

API Global

JavaScript 
// Acceder a todas las instancias
window.HequalizerAPI.Instances

// Crear instancia
window.HequalizerAPI.Init(elements, options)

// Remover instancia
window.HequalizerAPI.removeInstance(id)

Sistema Responsive

Hequalizer incluye un sistema responsive completo que permite configurar diferentes opciones según el viewport. Cada breakpoint puede sobrescribir cualquiera de las opciones base.

Cómo Funciona

  • Evaluación por viewport: Los breakpoints se evalúan con window.innerWidth ≤ breakpoint
  • Orden automático: Los breakpoints se ordenan de menor a mayor automáticamente
  • Configuración base: Si el viewport no coincide con ningún breakpoint, se usa la configuración base
  • Fusión de opciones: Las opciones del breakpoint activo se fusionan con las opciones base
  • Recalculación automática: Al cambiar de breakpoint, las alturas se recalculan automáticamente

Propiedades Configurables por Breakpoint

Todas las opciones disponibles pueden ser sobrescritas en cada breakpoint:

Propiedad Tipo Descripción Uso Responsive
cssVariable String Nombre de la variable CSS Útil para usar diferentes variables por dispositivo
columns String | Number Modo de columnas Cambia el número de columnas según el viewport (ej: 4 desktop, 2 tablet, 1 mobile)
initialIndex Number Índice desde donde iniciar Permite omitir elementos iniciales solo en ciertos viewports
resizeObserver Boolean Activar MutationObserver Mejora performance desactivándolo en móvil: resizeObserver: false
classElementToOmit String Clase para omitir elementos Permite omitir diferentes elementos según el dispositivo
on Object Lifecycle hooks Ejecuta lógica específica por breakpoint usando instance.actualBreakpoint

Ejemplo Básico

JavaScript 
new Hequalizer(elements, {
  // Configuración base (desktop > 1024px)
  columns: 3,
  cssVariable: '--desktop-height',

  responsive: {
    // Tablet (≤ 1024px)
    1024: {
      columns: 2,
      cssVariable: '--tablet-height'
    },
    // Mobile (≤ 768px)
    768: {
      columns: 1,
      cssVariable: '--mobile-height',
      resizeObserver: false // Mejora performance en móvil
    }
  }
});

Ejemplo Avanzado con Todas las Propiedades

JavaScript 
new Hequalizer(elements, {
  // Configuración base (desktop)
  cssVariable: '--height-desktop',
  columns: 4,
  initialIndex: 0,
  resizeObserver: true,
  classElementToOmit: '',

  on: {
    afterResize: ({rows, instance}) => {
      console.log('Breakpoint:', instance.actualBreakpoint);
      console.log('Columnas activas:', instance.actualOptions.columns);
    }
  },

  responsive: {
    // Large Tablet (≤ 1280px)
    1280: {
      columns: 3,
      cssVariable: '--height-lg-tablet'
    },

    // Tablet (≤ 1024px)
    1024: {
      columns: 2,
      cssVariable: '--height-tablet',
      initialIndex: 1 // Omite el primer elemento en tablet
    },

    // Mobile Landscape (≤ 768px)
    768: {
      columns: 2,
      cssVariable: '--height-mobile-landscape',
      classElementToOmit: 'hide-mobile' // Omite elementos con esta clase
    },

    // Mobile Portrait (≤ 480px)
    480: {
      columns: 1,
      cssVariable: '--height-mobile',
      resizeObserver: false, // Mejor performance
      initialIndex: 0,
      classElementToOmit: 'hide-mobile'
    }
  }
});
Importante:
  • Los breakpoints se evalúan con ≤ (menor o igual)
  • Se ordenan automáticamente de menor a mayor
  • Si no coincide ninguno, se usa la configuración base
  • Puedes acceder al breakpoint actual con instance.actualBreakpoint
  • Puedes acceder a las opciones aplicadas con instance.actualOptions

Ejemplos

Grid Responsive

JavaScript 
const gridItems = document.querySelectorAll('.grid-item');

new Hequalizer(gridItems, {
  columns: 3,
  responsive: {
    1024: { columns: 2 },
    768: { columns: 1 }
  }
});

Lifecycle Hooks

JavaScript 
const cards = document.querySelectorAll('.card');

new Hequalizer(cards, {
  on: {
    init: ({rows, instance}) => {
      console.log(`Altura inicial: ${rows}px`);
    },
    afterResize: ({rows, instance}) => {
      console.log(`Nueva altura: ${rows}px`);
    },
    afterChanges: ({rows, instance}) => {
      console.log('Contenido cambió, nueva altura:', rows);
    }
  }
});

Omitir Elementos

JavaScript 
const items = document.querySelectorAll('.item');

new Hequalizer(items, {
  classElementToOmit: 'skip-height'
});

Demos Interactivos

Demo 1: Grid Responsive

Grid de tarjetas con contenido variable. Los títulos se igualan automáticamente a la altura del más largo.

Demo 2: Carousel con Scroll Horizontal

Carousel horizontal con desplazamiento. Todas las descripciones tienen la misma altura para mantener el diseño consistente.

Código de los demos:

JavaScript - Grid Demo 
// Grid: Igualar títulos
const gridTitles = document.querySelectorAll('.grid-card-title');
new Hequalizer(gridTitles, {
  on: {
    init: ({rows, instance}) => {
      console.log(`Grid altura: ${rows}px`);
    }
  }
});
JavaScript - Carousel Demo 
// Carousel: Igualar descripciones
const carouselDescs = document.querySelectorAll('.carousel-card-desc');
new Hequalizer(carouselDescs, {
  on: {
    init: ({rows, instance}) => {
      console.log(`Carousel altura: ${rows}px`);
    }
  }
});