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.

Once you create a Hequalizer instance, it continues to maintain accurate height equalization automatically across several common scenarios: web font rendering, viewport resizing, and dynamic content changes. Understanding each mechanism helps you configure the library correctly and avoid subtle layout bugs.

​
Font loading

Hequalizer defers its initial init() call until document.fonts.ready resolves: 
document.fonts.ready.then(() => {
  this.init();
});
Web fonts can change the rendered height of text significantly. If init() ran before fonts loaded, the measured heights would be based on fallback font metrics and would be wrong. Waiting for document.fonts.ready ensures that all web fonts are available before any element heights are measured.
Create Hequalizer instances after DOMContentLoaded fires, or place your <script> tag at the end of <body>. This ensures your data-hequalizer elements already exist in the DOM when the constructor runs — otherwise querySelectorAll will find zero elements.
main.js
window.addEventListener('DOMContentLoaded', () => {
  new Hequalizer('card-title', {
    cssVariable: '--card-title-height'
  });
});

​
Resize listener

During init(), each instance registers a resize listener on window: 
window.addEventListener('resize', this._updateAfterResize);
Every time the window is resized, the handler:
  1. Calls _setActualOptions() to re-evaluate breakpoints and update actualOptions and actualBreakpoint.
  2. Cancels any pending debounce timeout (window.clearTimeout). This always happens — even when observeResize is false.
  3. If observeResize is false for the now-active options, the handler returns immediately without recalculating or emitting an event.
  4. If debounce is 0 (the default), recalculation happens synchronously on each resize event.
  5. If debounce is a positive number, recalculation is deferred by that many milliseconds; a new timeout is started, and will be cancelled by the next resize event that fires before it elapses.

​
Disabling resize recalculation

Set observeResize: false to prevent recalculation on resize for the active options set. The resize listener remains registered — it still updates actualOptions and actualBreakpoint — but it will not re-measure or update CSS variables:
main.js
new Hequalizer('card-title', {
  columns: 3,
  observeResize: false
});
This is useful when heights are fixed and do not need to change after the initial load, saving unnecessary computation.

​
Smoothing resize with debounce

By default, debounce: 0 means Hequalizer recalculates on every single resize event, which can fire dozens of times per second while a user drags the window edge. Use debounce to add a delay:
main.js
new Hequalizer('card-title', { debounce: 150 });
With debounce: 150, Hequalizer waits 150 milliseconds after the last resize event before recalculating. If another resize event fires during that window, the timeout resets.

​
Content change observer (MutationObserver)

After init(), Hequalizer attaches a MutationObserver to each element in the group. The observer watches for three types of changes:
  • childList — child elements added or removed
  • subtree — changes anywhere inside the element’s subtree
  • characterData — text node content changes
When any observed change is detected, Hequalizer waits 20ms (to let the DOM settle if multiple changes occur at once), then recalculates heights and emits hequalizer:{handle}:change:
main.js
const instance = new Hequalizer('card-title');

window.addEventListener('hequalizer:card-title:change', (event) => {
  console.log('Content changed. New heights:', event.detail.instance.values);
});
This means you never need to call update() manually when an element’s text or inner HTML changes dynamically — Hequalizer detects and responds to it automatically.

​
Adding or removing elements

The MutationObserver watches the content of existing elements, not the parent container for new siblings. If your application dynamically adds or removes elements that carry a data-hequalizer attribute, Hequalizer will not detect them automatically. After any DOM mutation that adds or removes group elements, call refreshElements():
main.js
const instance = new Hequalizer('card-title');

// Later, after dynamically rendering new cards into the DOM:
renderNewCards();
instance.refreshElements();
refreshElements() disconnects all existing observers, re-runs querySelectorAll with the original handle to pick up any new or removed elements, recalculates heights, then re-attaches observers to the updated element list.
Forgetting to call refreshElements() after adding or removing data-hequalizer elements is one of the most common sources of missed equalization. New elements will exist in the DOM with no height variable set, while removed elements will no longer affect the calculation — but Hequalizer will still hold references to them until you refresh.

​
Recalculation trigger summary

All five automatic and manual recalculation paths, along with the custom events they emit:
TriggerMethod calledEvent emitted
Font load completeinit()hequalizer:{handle}:init
Window resizeinternal (_updateAfterResize)hequalizer:{handle}:resize
Content change (MutationObserver)internal (_updateAfterChanges)hequalizer:{handle}:change
Manual recalculationupdate()hequalizer:{handle}:update
Manual element re-queryrefreshElements()hequalizer:{handle}:refresh
update() recalculates heights using the current $elements list — it does not re-query the DOM. If elements have been added or removed since the instance was created, use refreshElements() instead, which runs a fresh querySelectorAll to pick up the changes.
All events are dispatched on window and carry the Hequalizer instance in event.detail.instance:
main.js
window.addEventListener('hequalizer:card-title:init', (event) => {
  console.log('Ready. Calculated heights:', event.detail.instance.values);
});

window.addEventListener('hequalizer:card-title:resize', (event) => {
  console.log('Resize complete. Active breakpoint:', event.detail.instance.actualBreakpoint);
});

window.addEventListener('hequalizer:card-title:change', (event) => {
  console.log('Content changed:', event.detail.instance.values);
});

window.addEventListener('hequalizer:card-title:refresh', (event) => {
  console.log('Elements refreshed. Count:', event.detail.instance.$elements.length);
});

Build docs developers (and LLMs) love

Get started for freeTalk to us