htmxでHTTPレスポンスエラー時に任意のJavaScriptを実行する方法

こんにちは。エキサイトでデザイナーをしている齋藤です。

今回は、htmxでリクエスト発行してHTTPレスポンスエラーとなった場合に、任意のJavaScriptを実行する方法をご紹介します。

なお、本稿の内容は v2.0.6（2025年7月7日時点の最新版）のhtmxを前提とします。

htmxとは

htmxは、HTMLタグに専用の属性を記述することで、複雑なJSを記述せずにAJAXリクエストの発行を可能にするライブラリです。

マークアップの延長のような感覚でAJAXリクエストを実装できるのがhtmxの強みです。

<!-- クリックするとPOSTリクエストが発行される -->
<button type="button" hx-post="/sample" hx-trigger="click">
  送信
</button>

実現したいことを整理します。

既定のhtmxでは、リクエスト先から404や500が返却されてAJAXに失敗すると、ウェブコンソールにエラーメッセージが出力されます（console.errorが実行される）。

これにより、エラーを検知できますが、ブラウザの検証ツールを開く必要がありユーザーに対しては明示的ではありません。

一方で、今回実現したいことは、リクエスト先から404や500が返却されてAJAXに失敗した場合は、その旨を記したwindow.alertを実行して、簡易的にエラーメッセージを表示することです。

htmxが用意しているイベントの一つである、htmx:responseErrorを使用するとレスポンスエラーを検知できます。

これを、イベントに応答するスクリプトが埋め込めるhx-on属性と組み合わせると、レスポンスエラーが発生した場合に任意のJSが実行できます。

構文は以下の通りです。hx-onでイベントを指定する場合はキャメルケースをケバブケースに変換する必要があります。

hx-on:htmx:response-error="<任意のJavaScript>"

例えば、「クリックすると/sampleに対してPOSTリクエストを発行するボタンでレスポンスエラー時はwindow.alertを実行する」場合は以下のようにします。

<button 
type="button" 
hx-post="/sample" 
hx-trigger="click" 
hx-on:htmx:response-error="alert('処理に失敗しました')"
>
  リクエスト発行
</button>

これで、リクエスト先から404や500が返却されてAJAXに失敗した場合は、アラートダイアログが出現するように設定できました。

なお、200・300番台のレスポンスはこのイベントは発火しません。

今回は、htmxでリクエスト発行してHTTPレスポンスエラーとなった場合に、任意のJSを実行する方法をご紹介しました。

既定のconsole.errorでは一般ユーザーはエラーを検知できませんが、htmx:responseErrorイベントにより明示的にエラーを示すUIにできるため、特にユーザー操作が多い管理系のアプリケーションで活躍するのではないでしょうか。

htmxを使用される方の一助となれば幸いです。ご精読ありがとうございました。