ElementorのJavaScript APIは、ページ上のウィジェットが描画されたタイミングで独自の処理を実行したり、ウィジェットごとの動きをクラスとしてまとめたりするための仕組みです。中心になるのは、フロントエンドで使える elementorFrontend オブジェクトのフックと、ハンドラークラスの2つです。この記事では、スクリプトの読み込み方から、フックの使い方、ハンドラークラスの書き方、編集画面での注意点、動かないときの確認方法までを解説します。
ElementorのJavaScript APIの全体像
Elementorが読み込むJavaScriptには、大きく分けて2つの世界があります。
- フロントエンド：訪問者が見るページと、編集画面の中に表示されるプレビューの両方で動きます。グローバル変数
elementorFrontendを通じてフックやハンドラーを登録します。 - エディター：ページを編集する管理画面の側で動きます。グローバル変数
elementorや、コマンドを扱う$eが使えます。
独自のアニメーション、クリック時の開閉、外部ライブラリの初期化など、多くの用途はフロントエンド側だけで実現できます。この記事もフロントエンドを中心に説明し、エディター側は最後に要点だけを扱います。
なお、Elementorの内部APIは本体の更新で変わることがあります。ここで扱う内容は、Elementor 3系で広く使われてきたフロントエンドAPIの一般的な使い方です（2026年10月現在）。新しいエディター機能では仕組みが異なる場合があるため、使用中のバージョンの開発者向けドキュメントもあわせて確認してください。更新のたびに、ステージング環境で動作を確かめてから本番に反映してください。
スクリプトを正しいタイミングで読み込む
最初につまずきやすいのが読み込み方です。elementorFrontend はElementorのフロントエンド用スクリプトが読み込まれてから使えるようになるため、自分のスクリプトはそれより後に読み込む必要があります。
Elementorがフロントエンド用のスクリプトを読み込んだときに実行される elementor/frontend/after_enqueue_scripts アクションを使うと、Elementorで作ったページにだけ自分のスクリプトを追加できます。
<?php
// 子テーマの functions.php または独自プラグインに記述
add_action( 'elementor/frontend/after_enqueue_scripts', function () {
wp_enqueue_script(
'my-elementor-handlers',
get_stylesheet_directory_uri() . '/js/elementor-handlers.js',
array( 'elementor-frontend' ),
'1.0.0',
true
);
} );依存関係に elementor-frontend を指定しておくと、WordPressがElementorのスクリプトの後に読み込んでくれます。wp_enqueue_scripts で全ページに読み込んでしまうと、Elementorを使っていないページでエラーになったり、不要な読み込みが増えたりするため、このアクションを使う方が扱いやすくなります。
フロントエンドの初期化を待つ
スクリプトの中では、Elementorの初期化が終わったことを知らせる elementor/frontend/init イベントを待ってから、フックを登録します。
jQuery( window ).on( 'elementor/frontend/init', function () {
// ここで elementorFrontend.hooks などを使う
console.log( '編集画面か:', elementorFrontend.isEditMode() );
} );このイベントより前に elementorFrontend.hooks に触ると、未定義のエラーになったり、登録が間に合わなかったりします。
ウィジェットの描画に合わせて処理を実行する
elementorFrontend.hooks.addAction() で frontend/element_ready/ から始まるフックを登録すると、ウィジェットが描画されるたびにコールバックが呼ばれます。引数の $scope は、そのウィジェットの外側の要素をjQueryオブジェクトにしたものです。
jQuery( window ).on( 'elementor/frontend/init', function () {
// 画像ウィジェット（デフォルトスキン）が描画されるたびに呼ばれる
elementorFrontend.hooks.addAction( 'frontend/element_ready/image.default', function ( $scope ) {
// 描画済みの目印としてクラスを付け、CSSのフェードイン等に使う
$scope.addClass( 'my-image-ready' );
} );
} );フック名は「ウィジェット名.スキン名」の形です。対象のウィジェット名は、ページのHTMLで各ウィジェットに付いている data-widget_type 属性を見るとわかります（例：image.default、heading.default）。すべての要素を対象にしたい場合は frontend/element_ready/global、すべてのウィジェットなら frontend/element_ready/widget を使います。
ここで気をつけたいのは、$scope の外を検索しないことです。jQuery( '.my-button' ) のようにページ全体から探すと、同じウィジェットが複数あるときに、1つのウィジェットが描画されるたびに全部へイベントが重ねて登録されてしまいます。処理の範囲は $scope.find() で、そのウィジェットの中だけに限定します。
ハンドラークラスで動きをまとめる
開閉やスライダーのように、イベントの登録と解除、設定値の読み取りを伴う処理は、Elementorが用意している基底クラス elementorModules.frontend.handlers.Base を継承してまとめると管理しやすくなります。Elementor本体のウィジェットも同じ仕組みで作られています。
jQuery( window ).on( 'elementor/frontend/init', function () {
class ReadMoreHandler extends elementorModules.frontend.handlers.Base {
getDefaultSettings() {
return {
selectors: {
button: '.my-readmore__button',
body: '.my-readmore__body',
},
};
}
getDefaultElements() {
const selectors = this.getSettings( 'selectors' );
return {
$button: this.$element.find( selectors.button ),
$body: this.$element.find( selectors.body ),
};
}
bindEvents() {
this.elements.$button.on( 'click', this.onButtonClick.bind( this ) );
}
onButtonClick( event ) {
event.preventDefault();
this.elements.$body.toggleClass( 'is-open' );
}
}
// 独自ウィジェット my-readmore が描画されたらハンドラーを付ける
elementorFrontend.hooks.addAction( 'frontend/element_ready/my-readmore.default', function ( $element ) {
elementorFrontend.elementsHandler.addHandler( ReadMoreHandler, { $element: $element } );
} );
} );各メソッドの役割は次のとおりです。
getDefaultSettings()：使うセレクターなどの設定をまとめて返します。getDefaultElements()：設定のセレクターを使って、ウィジェット内の要素を取得します。this.$elementがウィジェット自身です。bindEvents()：イベントを登録します。ハンドラーが付いたときに呼ばれます。
ウィジェットのコントロールで設定した値をJavaScriptから読みたい場合は、ハンドラー内で this.getElementSettings() を使います。ただし、独自ウィジェットのPHP側で、そのコントロールにフロントエンドへ値を渡す指定（frontend_available）をしておく必要があります。
独自ウィジェットを作っている場合は、ウィジェットクラスの get_script_depends() でこのスクリプトのハンドル名を返すようにすると、ウィジェットが使われたページにだけ読み込まれます。
編集画面のプレビューで起きること
フロントエンドのスクリプトは、編集画面のプレビューの中でも実行されます。編集中はウィジェットの設定を変えるたびにそのウィジェットが描画し直され、frontend/element_ready/ のフックが何度も呼ばれます。前の節で触れたように、$scope の外にイベントを登録していると、編集画面でだけ動作が重複する原因になります。
編集画面とそれ以外で処理を分けたい場合は、elementorFrontend.isEditMode() で判定します。たとえば、ページ読み込み直後に自動でモーダルを開く処理は、編集中には邪魔になるため止めておくと作業しやすくなります。
ハンドラークラスでは、設定の変更を受け取る onElementChange() メソッドを定義すると、編集中にコントロールの値が変わったときに表示を更新できます。
エディター側のAPI
編集画面そのものを拡張したい場合は、PHPの elementor/editor/after_enqueue_scripts アクションでスクリプトを読み込み、グローバル変数 elementor のフックを使います。たとえば、特定のウィジェットの設定パネルが開かれたときに処理を実行するには、elementor.hooks.addAction( 'panel/open_editor/widget/heading', function ( panel, model, view ) { ... } ) のように書きます。
保存やパネルの操作などは $e というコマンドの仕組みで管理されています。エディター側は内部的な変更が比較的多い部分のため、使う前に公式の開発者向けドキュメントで現在の仕様を確認し、Elementorの更新後は動作を確かめるようにしてください。
動かないときの確認方法
思ったとおりに動かないときは、ブラウザの開発者ツールで次の順に確認します。
- **コンソールで
elementorFrontendと入力する**：未定義であれば、そのページでElementorのスクリプトが読み込まれていません。 - 自分のスクリプトが読み込まれているか：ネットワークタブでファイルが200で読み込まれているか、Elementorのスクリプトより後になっているかを見ます。
- 最適化プラグインの設定：JavaScriptの遅延実行や結合を行うプラグインを使っていると、
elementor/frontend/initが発生した後に自分のスクリプトが実行され、フックが登録されないことがあります。自分のスクリプトとElementorのスクリプトを遅延の対象から外して試します。 - フック名の綴り：
data-widget_typeの値とフック名が一致しているか、スキン名（.defaultなど）が抜けていないかを確認します。 - キャッシュ：JavaScriptを更新しても古いファイルが配信されている場合は、
wp_enqueue_script()のバージョン番号を上げるか、キャッシュを削除します。
まとめ
- フロントエンドの処理は、
elementor/frontend/after_enqueue_scriptsでスクリプトを読み込み、elementor/frontend/initを待ってから登録します。 frontend/element_ready/ウィジェット名.スキン名のフックで、ウィジェットが描画されるたびに処理を実行できます。範囲は$scopeの中に限定します。- 状態やイベントを伴う動きは
elementorModules.frontend.handlers.Baseを継承したハンドラークラスにまとめると管理しやすくなります。 - 編集画面のプレビューでも同じスクリプトが何度も動くため、重複登録と
isEditMode()による切り分けに注意します。 - 内部APIは更新で変わることがあるため、更新後はステージング環境で確認します。