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.

The Hequalizer constructor is the entry point for every height-equalization group. You call it once per group, passing a handle that ties the JavaScript instance to the HTML elements carrying the matching data-hequalizer attribute. The constructor validates the handle, queries matching elements, builds the full options map (base + each breakpoint), registers the instance in the global registry, and schedules init() to run after document.fonts.ready.

​
Signature

new Hequalizer(handle, options)

​
Parameters

​
handle
string
required
Unique identifier for the element group. Must match the data-hequalizer attribute value on every target element. Accepts only lowercase letters, numbers, and hyphens in slug format — validated against /^[a-z0-9]+(?:-[a-z0-9]+)*$/. The handle is used as the key in Hequalizer.instances and as part of every custom event name.
​
options
object
Optional configuration object applied to this instance. All properties are optional and fall back to built-in defaults when omitted. Breakpoint-specific overrides are nested inside the responsive key. See the Options reference for the full list of available properties.

​
What the constructor does

When you call new Hequalizer(handle, options), the following steps run synchronously before control returns:
  1. Validates the handle — checks it is present, matches the slug regex, and is not already registered in Hequalizer.instances.
  2. Queries elements — runs document.querySelectorAll('[data-hequalizer="${handle}"]') and stores the result in this.$elements.
  3. Builds allOptions — merges base defaults with options to produce allOptions.default, then iterates every breakpoint key in options.responsive to produce one merged entry per breakpoint.
  4. Collects cssVariables — extracts every unique cssVariable value across all option sets so they can all be cleaned before each recalculation.
  5. Registers the instance — calls Hequalizer.instances.set(handle, this) so the instance is immediately reachable via Hequalizer.getInstance().
  6. Defers init() — attaches a .then() handler to document.fonts.ready, ensuring heights are measured after web fonts have loaded and layout is stable.

​
Error scenarios

The constructor throws a synchronous Error for three invalid conditions. All error messages are in Spanish, matching the library’s source.
Missing handle — thrown when handle is undefined, null, an empty string, or any other falsy value.
Hequalizer: El parámetro handle es obligatorio
Invalid handle format — thrown when the handle contains uppercase letters, spaces, underscores, or any character outside [a-z0-9-].
Hequalizer: El handle "${handle}" no es válido. Utilice un identificador diferente.
Duplicate handle — thrown when a live instance with the same handle already exists in Hequalizer.instances. Call destroy() on the existing instance first if you need to reuse the handle.
Hequalizer: El handle "${handle}" ya está en uso. Utilice un identificador diferente.

​
Code examples

// Elements in your HTML carry data-hequalizer="card-title"
const instance = new Hequalizer('card-title');

​
HTML setup

Every element that should be height-equalized must carry the data-hequalizer attribute whose value exactly matches the handle string.
HTML
<div class="cards">
  <article class="card">
    <h3 data-hequalizer="card-title">Short title</h3>
  </article>
  <article class="card">
    <h3 data-hequalizer="card-title">A much longer title that wraps to two lines</h3>
  </article>
  <article class="card">
    <h3 data-hequalizer="card-title">Another title</h3>
  </article>
</div>
CSS
/* Hequalizer sets the variable; your CSS decides how to use it */
[data-hequalizer="card-title"] {
  min-height: var(--height);
}
The constructor immediately registers the instance and queries elements, but height calculation is deferred until document.fonts.ready resolves. Always create Hequalizer instances after the target elements already exist in the DOM — for example inside a DOMContentLoaded listener or at the bottom of the <body>.

Build docs developers (and LLMs) love

Get started for freeTalk to us