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.

Most Hequalizer problems fall into one of three categories: a mismatch between the constructor handle and the HTML attribute, a CSS rule that doesn’t consume the generated custom property, or a lifecycle timing issue where the instance is created before the DOM is ready or not destroyed when the view is torn down. The sections below walk through each known issue with its root cause and the steps to resolve it.
Problem: You’ve created a Hequalizer instance and your CSS is in place, but the elements all have different heights and the --height variable isn’t being applied.Root cause: The handle string passed to the constructor doesn’t exactly match the value of the data-hequalizer attribute on your elements. Hequalizer selects elements with document.querySelectorAll('[data-hequalizer="handle"]'), so even a single character difference results in zero elements being found.Solution: Verify that the constructor argument and the HTML attribute value are identical, including capitalisation (both must be lowercase), spacing (no spaces allowed), and punctuation (hyphens only).
Correct
<h3 data-hequalizer="card-title">Title</h3>
Correct
new window.Hequalizer('card-title');
Incorrect — attribute value doesn't match
<h3 data-hequalizer="cardTitle">Title</h3>
Incorrect — constructor handle doesn't match
new Hequalizer('card_title');
You can confirm what elements were found by reading the instance’s $elements property immediately after the hequalizer:card-title:init event fires:
window.addEventListener('hequalizer:card-title:init', (event) => {
  console.log('Elements found:', event.detail.instance.$elements.length);
});
Problem: Browser DevTools shows the --height inline custom property on your elements, but the elements don’t have equal heights.Root cause: No CSS rule is consuming the variable. Hequalizer only writes the custom property — it never sets height, min-height, or any other layout property directly. Your stylesheet must reference the variable for it to take effect.Solution: Add a CSS rule that applies the variable to a layout property. min-height is the most common choice because it allows content to grow beyond the equalised height without clipping:
styles.css
[data-hequalizer="card-title"] {
  min-height: var(--height);
}
If you initialised Hequalizer with a custom cssVariable name, use that name in your CSS instead of --height:
Initialised with custom variable
new window.Hequalizer('card-title', { cssVariable: '--card-title-height' });
styles.css
[data-hequalizer="card-title"] {
  min-height: var(--card-title-height);
}
Check the exact variable name written by DevTools on the element’s inline style attribute to confirm which name Hequalizer used.
Problem: The constructor throws Hequalizer: El handle "..." no es válido. Utilice un identificador diferente.Root cause: The handle contains characters outside the allowed pattern. Hequalizer validates handles against /^[a-z0-9]+(?:-[a-z0-9]+)*$/. Uppercase letters, spaces, underscores, dots, slashes, and other special characters are all rejected.Solution: Use a lowercase slug — the same format used in CSS class names and URL paths:
Valid handles
new window.Hequalizer('card-title');        // ✅ lowercase letters and hyphens
new window.Hequalizer('product-card-title'); // ✅ multi-segment slug
new window.Hequalizer('item2-label');        // ✅ numbers are allowed
Invalid handles
new Hequalizer('Card Title');   // ❌ uppercase and space
new Hequalizer('card_title');   // ❌ underscore
new Hequalizer('CardTitle');    // ❌ camelCase
new Hequalizer('card.title');   // ❌ dot
Problem: The constructor throws Hequalizer: El handle "..." ya está en uso. Utilice un identificador diferente.Root cause: An active instance with the same handle already exists in Hequalizer’s internal static Map. This often happens when a component mounts more than once without the previous instance being destroyed — for example, in a React component where useEffect runs twice in Strict Mode, or when a route component is unmounted and remounted without cleanup.Solution (preferred): Ensure destroy() is called before the component or view unmounts. In React:
React — correct lifecycle
useEffect(() => {
  const eq = new window.Hequalizer('product-title', { columns: 3 });

  return () => {
    eq.destroy(); // frees the handle on unmount
  };
}, []);
Solution (alternative): If you need to reuse an existing instance rather than create a new one, retrieve it with the static getInstance method:
const existing = window.Hequalizer.getInstance('product-title');
if (existing) {
  existing.refreshElements();
} else {
  new window.Hequalizer('product-title', { columns: 3 });
}
Problem: On narrow viewports, your equalized elements appear at their natural heights with no --height variable applied.Root cause: This is intentional behaviour. When the active breakpoint has columns: 1 (or any value ≤ 1), Hequalizer removes its CSS variables and state classes from all elements. A single-column layout has no need for height equalization because each element occupies a full row on its own.
columns: 1 disables equalization at that breakpoint
new window.Hequalizer('card-title', {
  columns: 3,
  responsive: {
    767: { columns: 1 } // ← equalization disabled at ≤ 767 px
  }
});
Solution: If you want equalization to remain active on mobile, increase the columns value for that breakpoint to 2 or higher. If the layout genuinely shows one column, the absence of equalization is correct and no change is needed.
Keep equalization active at ≤ 767 px
new window.Hequalizer('card-title', {
  columns: 3,
  responsive: {
    767: { columns: 2 } // equalization stays active, groups of 2
  }
});
Problem: After adding new elements with data-hequalizer to the DOM, they are not being equalized with the existing ones.Root cause: The MutationObserver that Hequalizer attaches to each element watches for content changes within those elements (text changes, child insertions). It does not watch the parent container for new sibling elements being added. Hequalizer’s $elements property is a static NodeList snapshot taken at construction time and does not automatically include nodes added later.Solution: Call refreshElements() after injecting new elements:
// After your fetch/render code adds new cards to the DOM:
window.Hequalizer.getInstance('card-title')?.refreshElements();
refreshElements() runs a fresh querySelectorAll, picks up newly added elements, re-attaches observers, recalculates heights, and emits a hequalizer:card-title:refresh event.
Problem: When the browser window is resized, the equalized heights stay fixed at the values calculated on load.Root cause: The active breakpoint’s options have observeResize: false. When this flag is set, Hequalizer’s resize listener updates the active breakpoint but skips the height recalculation step entirely for that breakpoint.Solution: Inspect the current options via instance.actualOptions to confirm:
const eq = window.Hequalizer.getInstance('card-title');
console.log(eq.actualOptions.observeResize); // false — that's the problem
Remove observeResize: false from the relevant breakpoint configuration, or set it to true explicitly:
Fix: enable resize observation
new window.Hequalizer('card-title', {
  columns: 3,
  responsive: {
    1024: {
      columns: 2,
      observeResize: true // was previously false
    }
  }
});
Problem: Performance is degraded during window resize because Hequalizer fires layout recalculations on every resize event tick.Root cause: debounce is 0 (the default), which means the recalculation runs synchronously on every resize event. Depending on browser and device, this can fire dozens of times per second while the user drags the resize handle.Solution: Set debounce to a value between 100 and 200 ms. This delays the recalculation until the user pauses resizing, greatly reducing the number of forced layout measurements:
Add a debounce to reduce resize recalculations
new window.Hequalizer('card-title', {
  columns: 3,
  debounce: 150
});
You can also set a different debounce per breakpoint if some breakpoints are more performance-sensitive than others:
new window.Hequalizer('card-title', {
  columns: 4,
  debounce: 0,          // immediate on desktop (fewer elements)
  responsive: {
    768: {
      columns: 2,
      debounce: 150     // debounced on tablet
    }
  }
});
Problem: The --height variable is applied but its value is 0px, or the .height-zero class is added to elements instead of .height-calculated.Root cause: Hequalizer measures offsetHeight on each element. If an element is hidden (display: none, visibility: hidden, or inside a hidden parent), or if it has no content at the time init() runs, offsetHeight returns 0. Because init() is called inside document.fonts.ready, it fires as soon as fonts are resolved — which may still be before a tab panel, modal, or lazy-loaded section becomes visible.Solution: Call update() after the elements become visible:
Call update() after showing a hidden section
document.getElementById('show-tab-btn').addEventListener('click', () => {
  document.getElementById('tab-panel').style.display = 'block';
  window.Hequalizer.getInstance('tab-title')?.update();
});
update() recalculates heights using the current actualOptions and emits hequalizer:{handle}:update. Unlike refreshElements(), it does not re-query the DOM — it uses the existing $elements list.
If you’ve worked through the steps above and the problem persists, open an issue on the GitHub repository and include the Hequalizer version, your browser and OS, a minimal reproduction, and the output of console.log(window.Hequalizer.getInstance('your-handle')). The issue tracker is at https://github.com/soyleninjs/hequalizer/issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us