Documentation Index
Fetch the complete documentation index at: https://mintlify.com/soyleninjs/hequalizer/llms.txt
Use this file to discover all available pages before exploring further.
Hequalizer is framework-agnostic — it has no dependencies and interacts only with the DOM and window. Any framework that renders HTML elements can use it. The only requirement is that the target elements exist in the DOM before you create an instance, and that you call destroy() when those elements are removed to prevent memory leaks and stale resize listeners.
React’s virtual DOM means elements are not available until after the component mounts. Create the Hequalizer instance inside a useEffect hook so it always runs after the initial render, and return destroy() as the cleanup function so React tears down the instance when the component unmounts.Load Hequalizer before your React app
Hequalizer ships as a plain script that sets window.Hequalizer. Add it to your HTML before your bundle, or import the file directly in your entry point:<script src="https://cdn.jsdelivr.net/npm/hequalizer/hequalizer.min.js"></script>
Create and destroy the instance in useEffect
import { useEffect, useRef } from 'react';
function ProductGrid() {
const hequalizerRef = useRef(null);
useEffect(() => {
hequalizerRef.current = new window.Hequalizer('product-title', {
columns: 3,
responsive: {
768: { columns: 1 }
}
});
return () => {
hequalizerRef.current?.destroy();
};
}, []);
return (
<div className="grid">
<h3 data-hequalizer="product-title">Product 1</h3>
<h3 data-hequalizer="product-title">Longer Product Name</h3>
<h3 data-hequalizer="product-title">Product 3</h3>
</div>
);
}
export default ProductGrid;
[] ensures the effect runs once on mount. The cleanup function returned from useEffect calls destroy(), which removes the resize listener, disconnects MutationObserver instances, and removes the instance from Hequalizer’s internal registry — freeing the handle for reuse.Refresh elements when the item list changes
If your component renders a dynamic list of items, call refreshElements() inside a second effect that depends on your items array:import { useEffect, useRef } from 'react';
function ProductGrid({ products }) {
const hequalizerRef = useRef(null);
useEffect(() => {
hequalizerRef.current = new window.Hequalizer('product-title', {
columns: 3
});
return () => {
hequalizerRef.current?.destroy();
};
}, []);
useEffect(() => {
hequalizerRef.current?.refreshElements();
}, [products]);
return (
<div className="grid">
{products.map((product) => (
<h3 key={product.id} data-hequalizer="product-title">
{product.title}
</h3>
))}
</div>
);
}
refreshElements() re-queries the DOM for [data-hequalizer="product-title"], picks up any newly rendered elements, and recalculates heights. Keep the Hequalizer instance in a useRef rather than useState. Storing it in state would trigger a re-render when the instance is assigned, which is unnecessary — the instance is a side-effect object, not UI state.
Vue 3’s Composition API provides onMounted and onUnmounted lifecycle hooks that map cleanly to Hequalizer’s create/destroy pattern.Create the instance in onMounted
<script setup>
import { onMounted, onUnmounted, ref } from 'vue';
const hequalizerInstance = ref(null);
onMounted(() => {
hequalizerInstance.value = new window.Hequalizer('card-title', {
columns: 3
});
});
onUnmounted(() => {
hequalizerInstance.value?.destroy();
});
</script>
<template>
<div class="grid">
<div v-for="card in cards" :key="card.id">
<h3 :data-hequalizer="'card-title'">{{ card.title }}</h3>
</div>
</div>
</template>
onMounted fires after Vue has written the component’s DOM to the page, so Hequalizer’s document.querySelectorAll call will find every [data-hequalizer="card-title"] element. onUnmounted runs destroy() before Vue removes the component from the DOM.React to dynamic list changes with a watcher
<script setup>
import { onMounted, onUnmounted, ref, watch, nextTick } from 'vue';
const props = defineProps({ cards: Array });
const hequalizerInstance = ref(null);
onMounted(() => {
hequalizerInstance.value = new window.Hequalizer('card-title', {
columns: 3
});
});
onUnmounted(() => {
hequalizerInstance.value?.destroy();
});
watch(
() => props.cards,
async () => {
await nextTick(); // wait for Vue to finish rendering new DOM nodes
hequalizerInstance.value?.refreshElements();
}
);
</script>
nextTick() ensures Vue has flushed its DOM updates before refreshElements() re-queries the document. Without a framework, listen for DOMContentLoaded to guarantee the document is fully parsed before querying elements.window.addEventListener('DOMContentLoaded', () => {
new window.Hequalizer('card-title', {
columns: 3,
debounce: 100
});
});
$elements will be an empty NodeList and no calculations are performed.Handling dynamic content in vanilla JS
If your page loads additional content via fetch or a third-party widget, grab the instance from the registry and call refreshElements():window.addEventListener('DOMContentLoaded', () => {
new window.Hequalizer('card-title', { columns: 3 });
});
// Later, after injecting new cards into the DOM:
function onMoreCardsLoaded() {
window.Hequalizer.getInstance('card-title')?.refreshElements();
}
Cleanup for manually managed views
If you build a single-page experience without a framework, destroy instances when tearing down a view and recreate them when the view is mounted again:function unmountProductView() {
window.Hequalizer.getInstance('product-title')?.destroy();
}
function mountProductView() {
document.getElementById('main').innerHTML = productViewHTML;
new window.Hequalizer('product-title', { columns: 3 });
}
When using Hequalizer with a SPA router (React Router, Vue Router, etc.), call destroy() when navigating away from any view that contains equalized elements, then create a new instance when that view mounts again. Failing to destroy leaves an orphaned resize listener and a registered handle that will cause the constructor to throw a “handle already in use” error the next time the view mounts.
Use window.Hequalizer.getInstance(handle) in component lifecycle hooks to access an existing instance without threading a reference through props or a context. Because Hequalizer maintains a static internal Map keyed by handle, getInstance always returns the live instance from anywhere in your application.
