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 works through a two-part contract: you mark HTML elements with a data-hequalizer attribute, then create a JavaScript instance using that same string as the handle. Hequalizer finds your elements, measures the tallest one, and writes the result as a CSS custom property — your stylesheet decides how to apply it.

​
The handle system

A handle is a short identifier that connects a group of HTML elements to a single Hequalizer instance. Every element that shares a handle will be measured together and receive the same CSS variable value.

​
Marking elements in HTML

Add data-hequalizer="your-handle" to every element in the group:
index.html
<div class="cards">
  <article class="card">
    <h3 data-hequalizer="card-title">Short title</h3>
    <p>Card body content.</p>
  </article>

  <article class="card">
    <h3 data-hequalizer="card-title">A much longer title that wraps to a second line</h3>
    <p>Card body content.</p>
  </article>

  <article class="card">
    <h3 data-hequalizer="card-title">Medium length title</h3>
    <p>Card body content.</p>
  </article>
</div>

​
Creating an instance in JavaScript

Pass the same string to the Hequalizer constructor:
main.js
window.addEventListener('DOMContentLoaded', () => {
  new Hequalizer('card-title');
});
Internally, the constructor runs: 
this.$elements = document.querySelectorAll(`[data-hequalizer="${handle}"]`);
All three <h3> elements above will be selected and equalized together.

​
Valid handle format

Handles must follow slug format: lowercase letters, numbers, and hyphens only. The constructor validates the handle against the regular expression /^[a-z0-9]+(?:-[a-z0-9]+)*$/ and throws an error if it does not match. 
new Hequalizer('card-title');           // ✅ letters and hyphens
new Hequalizer('product-title-2');      // ✅ letters, numbers, and hyphens
new Hequalizer('hero');                 // ✅ single word
new Hequalizer('blog-card-description'); // ✅ multiple hyphen-separated segments
Each handle can only be used by one active instance at a time. If you try to create a second instance with the same handle, Hequalizer throws an error. Retrieve an existing instance with Hequalizer.getInstance('your-handle') or call instance.destroy() before reusing the handle.

​
The CSS variable mechanism

After measuring all elements in the group, Hequalizer calls: 
element.style.setProperty(cssVariable, maxHeight + 'px');
This writes an inline CSS custom property directly onto each element. Your stylesheet then reads it with var():
styles.css
[data-hequalizer="card-title"] {
  min-height: var(--height);
}
The default variable name is --height. You can change it with the cssVariable option:
main.js
new Hequalizer('card-title', {
  cssVariable: '--card-title-height'
});
styles.css
[data-hequalizer="card-title"] {
  min-height: var(--card-title-height);
}

​
Complete working example

Here is a full example equalizing card titles across a grid layout.
1

Add data-hequalizer attributes to your HTML

index.html
<div class="cards">
  <article class="card">
    <h3 data-hequalizer="card-title">Wireless Headphones</h3>
    <p>Premium audio with noise cancellation.</p>
  </article>

  <article class="card">
    <h3 data-hequalizer="card-title">Portable Bluetooth Speaker with 360° Sound</h3>
    <p>Take your music anywhere.</p>
  </article>

  <article class="card">
    <h3 data-hequalizer="card-title">Smart Home Hub</h3>
    <p>Control all your devices from one place.</p>
  </article>
</div>
2

Create a Hequalizer instance

main.js
window.addEventListener('DOMContentLoaded', () => {
  new Hequalizer('card-title', {
    cssVariable: '--card-title-height'
  });
});
3

Apply the CSS variable in your stylesheet

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

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

​
Multiple groups

Each independent group of elements needs its own handle and its own Hequalizer instance. Handles within a page must be unique — two different groups must never share the same handle string.
index.html
<article class="product-card">
  <h3 data-hequalizer="product-title">Short name</h3>
  <p data-hequalizer="product-description">Short description.</p>
</article>
<article class="product-card">
  <h3 data-hequalizer="product-title">A much longer product name here</h3>
  <p data-hequalizer="product-description">A much longer description that wraps to multiple lines.</p>
</article>
main.js
const titles = new Hequalizer('product-title', {
  cssVariable: '--product-title-height'
});

const descriptions = new Hequalizer('product-description', {
  cssVariable: '--product-description-height'
});
styles.css
[data-hequalizer="product-title"] {
  min-height: var(--product-title-height);
}

[data-hequalizer="product-description"] {
  min-height: var(--product-description-height);
}
Each instance tracks only the elements belonging to its own handle. Changes in one group never affect the other.
Use descriptive, semantic handles that reflect the element’s role in the layout — for example feature-card-title, blog-post-excerpt, or testimonial-author. This makes multi-group setups easy to scan at a glance.

Build docs developers (and LLMs) love

Get started for freeTalk to us