Skip to main content

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.

Every Hequalizer instance exposes four public methods that cover the full lifecycle of a height-equalization group: initialization, manual recalculation, DOM re-querying, and teardown. Alongside those methods, the instance holds several readable properties that reflect the current state of the group — from the active breakpoint to the last set of calculated height values.

​
Methods

​
init()

Sets the active options and breakpoint for the current viewport, calculates maximum heights across all element groups, starts the window resize listener, attaches MutationObserver instances to each element, and emits the hequalizer:{handle}:init event. Signature: instance.init(): void
init() is called automatically after document.fonts.ready resolves. You only need to call it manually if you deliberately deferred or skipped the automatic initialization — for example, after calling destroy() and then deciding to reinitialize the same instance object without creating a new one.
const instance = new Hequalizer('card-title');

// init() runs automatically — you rarely need to call it yourself.
// If you ever need to trigger it manually:
instance.init();

​
update()

Recalculates maximum heights for all currently tracked elements using the currently active options, then emits hequalizer:{handle}:update. Unlike refreshElements(), it does not re-query the DOM — the element list stays the same. Signature: instance.update(): void Use update() when you know element heights have changed but no DOM mutation was observed — for example after a lazy-loaded image finishes loading, after an animation completes, or after toggling hidden content that affects layout. 
const instance = new Hequalizer('card-title');

// A lazy image finished loading — recalculate heights
document.querySelector('.card img').addEventListener('load', () => {
  instance.update();
});

// After programmatically toggling content
document.querySelector('#toggle-btn').addEventListener('click', () => {
  document.querySelector('.extra-content').classList.toggle('visible');
  instance.update();
});

​
refreshElements()

Disconnects existing MutationObserver instances, re-runs document.querySelectorAll('[data-hequalizer="${handle}"]') to capture any new or removed elements, updates active options for the current breakpoint, recalculates heights, reconnects observers on the new element set, and emits hequalizer:{handle}:refresh. Signature: instance.refreshElements(): void Use refreshElements() whenever elements are added to or removed from the group in the DOM. The MutationObserver watches for content changes inside existing elements but does not detect new elements being inserted into the page. 
const instance = new Hequalizer('product-title');

// After dynamically rendering more product cards
async function loadMoreProducts() {
  const newCards = await fetchProducts();
  renderCards(newCards); // appends elements with data-hequalizer="product-title"
  instance.refreshElements(); // pick up the newly rendered elements
}

// After removing elements from the group
function removeCard(cardEl) {
  cardEl.remove();
  instance.refreshElements();
}

​
destroy()

Performs a full teardown of the instance: resets values to 0, clears all tracked CSS custom properties from element inline styles, removes all state classes, removes the window resize listener, disconnects and deletes all MutationObserver instances, cancels any pending debounced resize or content-change timeouts, emits hequalizer:{handle}:destroy, and finally removes the instance from Hequalizer.instances — freeing the handle for reuse. Signature: instance.destroy(): void 
const instance = new Hequalizer('card-title');

// Tear down when a component unmounts
function onUnmount() {
  instance.destroy();
}

// After destroy, the handle is free — a new instance can use it
instance.destroy();
const fresh = new Hequalizer('card-title'); // ✅ no duplicate-handle error

// React example — cleanup in useEffect
useEffect(() => {
  const eq = new window.Hequalizer('product-title', { columns: 3 });
  return () => eq.destroy();
}, []);
After destroy() is called, the instance object still exists in memory but is no longer registered in Hequalizer.instances and will not respond to resize or content-change events. Do not call other methods on a destroyed instance.

​
Instance properties

The following properties are set during construction and updated as the instance runs. They are publicly readable and useful for debugging or reacting to state inside event listeners.
​
handle
string
The handle string passed to the constructor. Used as the map key in Hequalizer.instances and as part of all custom event names.
​
$elements
NodeList
The live collection of elements matched by [data-hequalizer="{handle}"]. Updated by refreshElements(). Reflects the DOM state at the time of the last query.
​
values
number | number[]
The last calculated height value(s). When columns is "all", this is a single number — the maximum offsetHeight across all elements. When columns is a number greater than 1, this is an array of numbers, one per group. Resets to 0 after destroy().
// columns: "all"
console.log(instance.values); // 140

// columns: 3  (with 9 elements → 3 groups)
console.log(instance.values); // [120, 160, 140]
​
actualOptions
object
The fully resolved options object currently in use — either allOptions.default or the merged breakpoint options, depending on window.innerWidth. Updated every time a resize event fires or _setActualOptions() runs internally.
​
actualBreakpoint
string | number
The identifier of the currently active breakpoint. Set to the string "default" when no responsive breakpoint matches window.innerWidth, or to the numeric breakpoint value (e.g., 768) when one does.
window.addEventListener('hequalizer:card-title:resize', (e) => {
  console.log(e.detail.instance.actualBreakpoint); // "default" or 768
});
​
responsive
object
The raw responsive object passed into the constructor options. Keyed by breakpoint number; values are partial option objects. This is the original reference — not the merged per-breakpoint copies stored in allOptions.
​
breakpoints
number[]
The sorted array of numeric breakpoint keys extracted from the responsive option, ordered from smallest to largest. Used internally to determine which breakpoint is active on each resize.
// options.responsive = { 1024: {...}, 768: {...}, 480: {...} }
console.log(instance.breakpoints); // [480, 768, 1024]
​
cssVariables
string[]
An array of all unique CSS custom property names tracked across the default options and every breakpoint. Because different breakpoints can declare different cssVariable values, Hequalizer needs to clear all of them before each recalculation to avoid stale values from a previous breakpoint.
// If default uses '--height' and the 768bp uses '--height-mobile':
console.log(instance.cssVariables); // ['--height', '--height-mobile']

Build docs developers (and LLMs) love

Get started for freeTalk to us