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.

Hequalizer’s handle-based API makes it straightforward to apply height equalization to almost any layout pattern. The examples below cover the most common scenarios — each one shows the HTML markup, the JavaScript initialization, and the CSS needed to consume the generated custom property.

​
Responsive Grid

Card grids are the most frequent use case for Hequalizer. When a grid switches between three columns on desktop, two on tablet, and one on mobile, the column grouping must match the visual layout at every breakpoint — otherwise elements in separate visual rows would share a height calculation that doesn’t apply to them.
1

Add data-hequalizer to your heading elements

Mark every heading that belongs to the same equalization group with a matching data-hequalizer attribute. The value must be a lowercase slug — the same string you’ll pass to the constructor.
index.html
<div class="grid">
  <article class="card">
    <h3 data-hequalizer="grid-title">Title 1</h3>
    <p>Card content.</p>
  </article>
  <article class="card">
    <h3 data-hequalizer="grid-title">Longer title that wraps to a second line</h3>
    <p>Card content.</p>
  </article>
  <article class="card">
    <h3 data-hequalizer="grid-title">Title 3</h3>
    <p>Card content.</p>
  </article>
</div>
2

Initialize Hequalizer with matching column counts

Pass columns: 3 to match the three-column desktop layout. The responsive map mirrors the CSS breakpoints — 1024 switches to two columns and 640 drops to one column, which automatically clears all CSS variables so mobile titles use their natural height.
main.js
new window.Hequalizer('grid-title', {
  columns: 3,
  responsive: {
    1024: { columns: 2 },
    640: { columns: 1 }
  }
});
Hequalizer sorts breakpoints from smallest to largest internally and picks the first one where window.innerWidth <= breakpoint. If no breakpoint matches, it falls back to the top-level columns: 3 default.
3

Apply the CSS variable in your stylesheet

Hequalizer writes a --height inline custom property to each element. Your CSS decides how to use it — min-height is the most common choice because it lets shorter elements grow to match the tallest one without clipping taller content.
styles.css
[data-hequalizer="grid-title"] {
  min-height: var(--height);
}
Set columns in your JavaScript to mirror the column count in your CSS grid or flexbox layout exactly. If your grid shows four columns but Hequalizer groups by three, rows will be misaligned.

​
Multiple Independent Groups

A product card typically has at least two elements that need separate equalization: the title and the description. Each group requires its own handle and — to avoid conflicts — its own CSS custom property name.
1

Mark each group with a distinct handle

index.html
<article class="product-card">
  <h3 data-hequalizer="product-title">Product Name</h3>
  <p data-hequalizer="product-description">Short description.</p>
</article>
<article class="product-card">
  <h3 data-hequalizer="product-title">Longer Product Name Here</h3>
  <p data-hequalizer="product-description">A longer description that takes up more vertical space.</p>
</article>
2

Create one instance per group with custom variable names

Each instance manages its own set of elements and writes to its own CSS variable. Providing explicit cssVariable names avoids both groups writing to the default --height property and overwriting each other.
main.js
new window.Hequalizer('product-title', {
  cssVariable: '--product-title-height'
});

new window.Hequalizer('product-description', {
  cssVariable: '--product-description-height'
});
3

Consume each variable independently in CSS

styles.css
[data-hequalizer="product-title"] {
  min-height: var(--product-title-height);
}

[data-hequalizer="product-description"] {
  min-height: var(--product-description-height);
}
You can create as many independent groups as your layout needs. Each instance tracks its own elements, breakpoints, and CSS variable — they never interfere with one another. Retrieve any active instance later with window.Hequalizer.getInstance('product-title') without keeping a reference yourself.
A carousel that lazy-loads additional slides presents two challenges: the resize debounce must be generous enough not to thrash recalculations during drag gestures, and the instance must re-query the DOM after new slides are injected.
1

Initialize with a debounce suitable for carousel interactions

main.js
const titleEq = new window.Hequalizer('slide-title', {
  columns: 'all',
  debounce: 100
});
columns: 'all' equalizes every slide in the carousel to the same height regardless of how many are visible at once. The debounce: 100 value delays the resize recalculation by 100 ms, which prevents excessive layout thrashing when the user resizes the browser or the carousel adjusts its own dimensions.
2

Listen for the init event to confirm equalization

main.js
window.addEventListener('hequalizer:slide-title:init', (event) => {
  console.log('Slides equalized:', event.detail.instance.values);
});
event.detail.instance is the live Hequalizer instance. values holds the single maximum height (a Number) when columns is 'all', or an array of per-row maximums when columns is a number.
3

Call refreshElements() after dynamic content loads

When the carousel appends new slides to the DOM, Hequalizer’s existing MutationObserver watches content changes inside already-tracked elements — it does not detect brand-new elements added outside those nodes. Call refreshElements() explicitly after the carousel injects new slides.
main.js
// Triggered by your carousel's "slides loaded" callback:
titleEq.refreshElements();
refreshElements() re-runs document.querySelectorAll('[data-hequalizer="slide-title"]'), re-attaches observers to any new elements, recalculates heights, and emits a hequalizer:slide-title:refresh event.
Do not call refreshElements() inside a tight render loop. It re-queries the DOM and forces a layout measurement. Once per batch of new slides is the correct pattern.

​
Disable Equalization on Mobile

On a single-column mobile layout, all cards stack vertically and share no row with neighbours — height equalization is unnecessary and adds unhelpful min-height constraints. Setting columns: 1 (or any value ≤ 1) at a breakpoint tells Hequalizer to clean up its CSS variables and state classes without destroying the instance.
main.js
new window.Hequalizer('card-title', {
  columns: 3,
  responsive: {
    767: { columns: 1 } // columns <= 1 clears variables; no height applied
  }
});
When the viewport is 767 px or narrower, Hequalizer:
  1. Removes the --height inline custom property from every element.
  2. Removes all state classes (height-calculated, height-zero, height-calculating).
  3. Skips the height measurement step — no offsetHeight reads and no CSS variable assignment occur.
When the viewport widens past 767 px again, the instance picks up the columns: 3 default and resumes equalizing automatically — no manual intervention needed.
This pattern is the idiomatic way to opt out of height equalization at a breakpoint. It is preferable to calling destroy() because the instance remains registered and will resume correct behaviour as the user resizes their browser.

Build docs developers (and LLMs) love

Get started for freeTalk to us