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 responsive option lets you provide a different set of options for each viewport width range. This is essential for grid layouts where the number of visible columns changes at various breakpoints — your height equalization should match the actual column count at every size.

​
The responsive option

Pass an object keyed by numeric breakpoints (in pixels). Each value is a partial options object that overrides the base configuration when that breakpoint is active:
main.js
new Hequalizer('product-title', {
  cssVariable: '--product-title-height',
  columns: 4,
  debounce: 100,
  responsive: {
    1024: { columns: 3 },
    768: {
      columns: 2,
      cssVariable: '--product-title-height-tablet'
    },
    480: { columns: 1 }
  }
});
Breakpoint options merge with the base options — they do not replace them. Any key you omit at a breakpoint falls back to the base value.

​
How breakpoints are matched

When the window resizes (or on first load), Hequalizer sorts all breakpoints from smallest to largest, then finds the first one where window.innerWidth <= breakpoint. That becomes the active breakpoint. If no breakpoint matches — meaning the viewport is wider than all defined breakpoints — Hequalizer uses the base "default" configuration. The currently active breakpoint is always available on the actualBreakpoint property: 
const instance = new Hequalizer('product-title', {
  columns: 4,
  responsive: {
    1024: { columns: 3 },
    768: { columns: 2 },
    480: { columns: 1 }
  }
});

// On a 900px-wide viewport:
console.log(instance.actualBreakpoint); // 1024
console.log(instance.actualOptions.columns); // 3
actualBreakpoint is "default" when no breakpoint applies, or the matching breakpoint number otherwise.

​
Viewport-to-breakpoint mapping

Using the configuration from the example above, the resulting behavior at each viewport width is:
Viewport widthActive breakpointEffective options
≤ 480px480columns: 1
481px – 768px768columns: 2, cssVariable: '--product-title-height-tablet'
769px – 1024px1024columns: 3
> 1024pxdefaultcolumns: 4
Breakpoints are evaluated as less than or equal to (<=), so a viewport of exactly 768px activates the 768 breakpoint, not 1024.

​
CSS variable cleanup across breakpoints

When you assign a different cssVariable at a specific breakpoint, two different CSS custom properties may be set on your elements across viewport changes. Hequalizer prevents stale values by tracking every CSS variable name used in any breakpoint — stored in the cssVariables array — and removing all of them before each recalculation: 
// Hequalizer builds this array automatically:
instance.cssVariables;
// => ['--product-title-height', '--product-title-height-tablet']
Before applying fresh values, _cleanHeightElements() calls element.style.removeProperty() for each variable in that array. This means switching from the tablet breakpoint back to desktop never leaves --product-title-height-tablet lingering on the element.

​
Corresponding CSS for per-breakpoint variables

Write one min-height rule per variable, scoped to the correct media query:
styles.css
[data-hequalizer="product-title"] {
  min-height: var(--product-title-height);
}

@media (max-width: 768px) {
  [data-hequalizer="product-title"] {
    min-height: var(--product-title-height-tablet);
  }
}
The CSS media queries and the JavaScript breakpoints work in parallel: the browser picks which min-height declaration to apply, and Hequalizer ensures only the correct variable has a value at any given time.

​
Full responsive example

1

HTML: mark your elements

index.html
<div class="product-grid">
  <article class="product-card">
    <h3 data-hequalizer="product-title">Wireless Earbuds</h3>
  </article>
  <article class="product-card">
    <h3 data-hequalizer="product-title">Over-Ear Studio Headphones with Active Noise Cancellation</h3>
  </article>
  <article class="product-card">
    <h3 data-hequalizer="product-title">Portable Speaker</h3>
  </article>
  <article class="product-card">
    <h3 data-hequalizer="product-title">Smart Soundbar</h3>
  </article>
</div>
2

JavaScript: configure responsive breakpoints

main.js
window.addEventListener('DOMContentLoaded', () => {
  new Hequalizer('product-title', {
    cssVariable: '--product-title-height',
    columns: 4,
    debounce: 100,
    responsive: {
      1024: { columns: 3 },
      768: {
        columns: 2,
        cssVariable: '--product-title-height-tablet'
      },
      480: { columns: 1 }
    }
  });
});
3

CSS: apply each variable at the right breakpoint

styles.css
.product-grid {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  gap: 1.5rem;
}

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

@media (max-width: 768px) {
  .product-grid {
    grid-template-columns: repeat(2, 1fr);
  }

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

@media (max-width: 480px) {
  .product-grid {
    grid-template-columns: 1fr;
  }
}

​
Disabling equalization at mobile breakpoints

Set columns: 1 at a mobile breakpoint to disable height equalization entirely on small screens without calling destroy(). Hequalizer will clear all CSS variables and state classes, letting elements return to their natural height in a single-column layout. See the Column Modes page for the full details on how columns: 1 behaves.
main.js
new Hequalizer('card-title', {
  columns: 3,
  responsive: {
    640: { columns: 1 } // natural heights on mobile
  }
});

Build docs developers (and LLMs) love

Get started for freeTalk to us