match-height-vanilla

jQuery不要の高さ揃えライブラリ
既存の jquery.matchHeight.js の思想を引き継ぎつつ、バニラJS（UMD）で再実装しました。
行単位（byRow）での高さ揃え、data-mh によるグルーピング、update/destroy などのAPIを提供します。

• 後継ポイント: jquery.matchHeight.js の挙動・使い勝手を尊重しつつ、jQuery依存を排除（DOM APIのみで動作）
• 対象ユースケース: 横に並んだカードの高さ揃え、レスポンシブ時の自動再計測、data-mh でのグループ指定

---

インストール

CDN / 直読み

<script src="./matchHeight.vanilla.js"></script>
<script>
  // グローバルに matchHeight が追加されます。
  matchHeight('[data-mh="group"]', { byRow: true });
</script>

npm // 準備中

npm i match-height-vanilla

CommonJS (Node/Bundler):

const matchHeight = require('match-height-vanilla');
matchHeight('[data-mh="group"]');

ESM import（UMDをdefaultとして解決される環境で）:

import matchHeight from 'match-height-vanilla';
matchHeight('[data-mh="group"]');

注: 本ライブラリは UMD 配布です。多くのバンドラ（Vite/Webpack/Rollup）では default import として読み込めます。もしうまく解決されない場合は require(...) をご利用ください。

---

使い方（最短サンプル）

<div class="grid">
  <div class="card" data-mh="group1">短い</div>
  <div class="card" data-mh="group1">長い長い長いテキスト</div>
  <div class="card" data-mh="group1">中くらい</div>
</div>

<script src="./matchHeight.vanilla.js"></script>
<script>
  // data-mh="group1" の要素を行ごとに最大値で揃える
  matchHeight('[data-mh="group1"]', { byRow: true });

  // 画面サイズ変化等に追従させたい場合
  matchHeight.enableAutoUpdate();
</script>

---

API

matchHeight(elements, options?)

指定要素の高さを揃えます。

• elements: string | Element | Element[] | NodeList

• options:

  • byRow (boolean, default: true): 行（同じ getBoundingClientRect().top を持つグループ）ごとに揃える
  • property ('minHeight' | 'height', default: 'minHeight'): どのCSSプロパティで揃えるか
  • target (Element | null, default: null): 指定した要素の高さに合わせる
  • tolerance (number, default: 1): 行判定の誤差許容(px)

matchHeight('.card', { byRow: true });              // 行ごと
matchHeight('.plan', { byRow: false });             // 全体で最大値
matchHeight('.col',  { target: document.querySelector('.primary') }); // 指定要素に合わせる

matchHeight.scan(root?, options?)

[data-mh] を持つ要素をスキャンし、グループ名ごとに高さ揃えします。

matchHeight.scan();                 // document 全体をスキャン
matchHeight.scan(rootEl, { byRow: true, property: 'minHeight' });

matchHeight.update(elements?)

再計測して再適用します。elements 省略時は内部レジストリ全体を更新します。 非表示（display:none）→表示に切り替えた直後などに有効。

matchHeight.update();           // すべて再計測
matchHeight.update('.card');    // 指定セレクタのみ再計測

matchHeight.destroy(elements)

指定要素の高さ揃えを解除（inline styleをクリア）します。

matchHeight.destroy('.card');

matchHeight.destroyAll()

すべての要素に対して解除します。

matchHeight.destroyAll();

matchHeight.enableAutoUpdate() / disableAutoUpdate()

ResizeObserver が使える環境ではそれを、無い環境では window.resize をスロットルして再計測を自動化します。

matchHeight.enableAutoUpdate();
// matchHeight.disableAutoUpdate();

---

data-mh グルーピング

HTML上でグループ名を付けると、scan() でまとめて高さ揃えできます。

<div data-mh="group">A</div>
<div data-mh="group">B</div>
<div data-mh="group">C</div>

<script>
  matchHeight.scan(); // "group" ごとに行単位で揃える
</script>

---

互換性と注意点

• 非表示要素（display:none）は計測できません。表示タイミングで matchHeight.update() を呼んでください。
• デフォルトでは min-height を使います。height で揃えたい場合は property: 'height' を指定してください。
• 行判定は getBoundingClientRect().top をもとに tolerance（初期値 1px）で近似マッチさせています。フォントロードやズーム差で微妙にズレるケースでは tolerance を上げてください。
• box-sizing が混在していると見た目に差が出る場合があります。必要に応じて CSS を統一してください。

---

jQuery版からの移行

• 目的は同じ（複数要素の高さ揃え）ですが、jQuery依存なしで軽量化しています。

• 代表的な移行例：

  • 旧：$('[data-mh="group"]').matchHeight(); 新：matchHeight.scan();（または matchHeight('[data-mh="group"]')）
  • 旧：$('.item').matchHeight({ byRow: false }); 新：matchHeight('.item', { byRow: false });
  • 旧：$('.item').matchHeight({ remove: true }); 新：matchHeight.destroy('.item');

---

ライセンス

MIT このライブラリは、jquery.matchHeight.js のコンセプトに基づき、jQuery非依存のUMDライブラリとして再実装したものです。オリジナルへの敬意を表します。

---

変更履歴（抜粋）

• 0.1.0 初版（UMD配布・scan/update/destroy・enableAutoUpdate 実装）