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.

Getting Hequalizer running takes three steps: mark the elements you want to equalize in HTML, create an instance in JavaScript that targets those elements by handle, and write a CSS rule that consumes the variable Hequalizer sets. The entire workflow — from zero to equalized heights — is covered below.
1

Mark elements in HTML

Add a data-hequalizer attribute to every element that should share a height. The attribute value is the handle — a lowercase slug string that uniquely identifies this group on the page.
index.html
<div class="cards">
  <article class="card">
    <h3 data-hequalizer="card-title">Short title</h3>
    <p>Card body.</p>
  </article>
  <article class="card">
    <h3 data-hequalizer="card-title">A longer title that wraps to multiple lines</h3>
    <p>Card body.</p>
  </article>
  <article class="card">
    <h3 data-hequalizer="card-title">Another title</h3>
    <p>Card body.</p>
  </article>
</div>
The handle value ("card-title" here) must be a lowercase slug — letters, numbers, and hyphens only. Every element in this group shares the same data-hequalizer value, and that value must exactly match the string you pass to the Hequalizer constructor in the next step.
You can have as many independent groups as you need on a single page. Just use a different handle for each group — for example "card-title", "card-description", "card-image" — and create a separate Hequalizer instance for each.
2

Create a Hequalizer instance

After the DOM has been parsed, instantiate Hequalizer with the same handle string you used in the HTML.
main.js
window.addEventListener('DOMContentLoaded', () => {
  new window.Hequalizer('card-title');
});
When the constructor runs, Hequalizer:
  1. Validates the handle: throws if it is missing, throws if it does not match the required slug format (/^[a-z0-9]+(?:-[a-z0-9]+)*$/), and throws if the same handle is already in use by another active instance.
  2. Runs document.querySelectorAll('[data-hequalizer="card-title"]') to collect the elements.
  3. Registers the instance in the static Hequalizer.instances map.
  4. Waits for document.fonts.ready so web fonts are fully loaded and offsetHeight measurements are accurate.
  5. Calls init() automatically (via document.fonts.ready) — which calculates the maximum height, writes the CSS variable, and starts the resize listener and MutationObservers. You rarely need to call init() manually.
Because Hequalizer defers to document.fonts.ready, the initial calculation always reflects true rendered heights — even when custom fonts cause text to reflow after the DOM loads.
3

Consume the CSS variable

Hequalizer writes the calculated height as an inline CSS custom property named --height on each element. Add a CSS rule that uses that variable however your design requires.
styles.css
[data-hequalizer="card-title"] {
  min-height: var(--height);
}
--height is the default variable name. Hequalizer sets it as an inline style (e.g. style="--height: 64px;") on every element in the group after measuring the tallest one.
Use min-height rather than height so that elements can still grow beyond the equalized value if their content requires it — for example when a user resizes the browser and text reflows.
You can override the variable name per instance or per breakpoint using the cssVariable option:
new window.Hequalizer('card-title', {
  cssVariable: '--card-title-height'
});

[data-hequalizer="card-title"] {
  min-height: var(--card-title-height);
}

​
What happens next

Once init() completes, Hequalizer continues to maintain equal heights automatically without any further intervention. Resize handling — A window resize listener is registered and remains active for the lifetime of the instance. On every resize event, Hequalizer re-evaluates the active breakpoint, recalculates the maximum height, and updates the CSS variable on all elements. You can add a debounce value (in milliseconds) to throttle recalculation during rapid resize events. Content change watching — Each element in the group is observed by its own MutationObserver configured to watch childList, subtree, and characterData. If the text or child nodes of any element change — for example because dynamic content is injected — Hequalizer waits 20 ms and then recalculates automatically, emitting a hequalizer:card-title:change event when done. Instance registry — The instance is stored in a static Map keyed by handle. You do not need to hold a variable reference to interact with it later: 
// Retrieve the instance anywhere in your codebase
const eq = window.Hequalizer.getInstance('card-title');

// Manually trigger a recalculation
eq.update();

// Re-query the DOM after adding or removing elements
eq.refreshElements();

// Tear everything down cleanly
eq.destroy();

Add Responsive Breakpoints

Learn how to configure different columns, cssVariable, and debounce values at specific viewport widths using the responsive option.

Full Constructor Reference

Explore every option available in the Hequalizer constructor, including all default values, valid input formats, and the complete instance API.

Build docs developers (and LLMs) love

Get started for freeTalk to us