htmx でファイルアップロードを簡単に実装する

2025年8月16日

htmx

Web アプリケーションでファイルアップロード機能を実装する際、従来の JavaScript ベースの手法では複雑な状態管理やイベントハンドリングが必要でした。しかし、htmx を使えば HTML の属性だけで、驚くほどシンプルにファイルアップロード機能を実装できます。

本記事では、htmx を活用したファイルアップロードの実装方法を、基本的な単一ファイルから複数ファイル、プログレスバー付き、ドラッグ&ドロップ対応まで段階的に解説していきます。

背景

従来の JavaScript ファイルアップロードの複雑さ

従来の JavaScript を使ったファイルアップロードでは、多くの処理を手動で実装する必要がありました。ファイル選択時のイベントリスナー、FormData オブジェクトの作成、XMLHttpRequest や Fetch API の設定、アップロード進捗の監視、エラーハンドリングなど、膨大なコード量になることが珍しくありません。

javascript// 従来の JavaScript でのファイルアップロード例
const fileInput = document.getElementById('file-input');
const uploadButton = document.getElementById('upload-btn');
const progressBar = document.getElementById('progress');

uploadButton.addEventListener('click', async () => {
    const file = fileInput.files[0];
    if (!file) return;
    
    const formData = new FormData();
    formData.append('file', file);
    
    try {
        const response = await fetch('/upload', {
            method: 'POST',
            body: formData,
            onUploadProgress: (event) => {
                const progress = (event.loaded / event.total) * 100;
                progressBar.style.width = progress + '%';
            }
        });
        
        if (response.ok) {
            // 成功処理
        } else {
            // エラー処理
        }
    } catch (error) {
        // エラーハンドリング
    }
});

このアプローチでは、DOM 操作、状態管理、エラーハンドリングが複雑に絡み合い、保守性の低いコードになりがちでした。

htmx の特徴とファイルアップロードでの優位性

htmx は「HTML as a Programming Language」という哲学のもと、HTML 属性だけで動的な Web アプリケーションを構築できるライブラリです。ファイルアップロードにおいて、htmx が提供する主な優位性は以下の通りです。

以下の図は htmx とサーバーサイドの基本的な連携構造を示しています。

mermaidflowchart LR
    html[HTML フォーム] -->|hx-post| htmx[htmx ライブラリ]
    htmx -->|ファイル送信| server[サーバー]
    server -->|HTML レスポンス| htmx
    htmx -->|DOM 更新| target[指定要素]

htmx では、JavaScript コードを書くことなく、HTML 属性の設定だけでファイルアップロードを実現できます。

図で理解できる要点：

HTML フォームに htmx 属性を追加するだけで機能実装が完了
サーバーからの HTML レスポンスが自動的に DOM に反映される
複雑な状態管理やイベントハンドリングが不要

課題

JavaScript フレームワークでのファイルアップロード実装の手間

React、Vue.js、Angular などのモダンフレームワークでファイルアップロードを実装する場合、コンポーネント設計、状態管理、ライフサイクル管理など、考慮すべき要素が多数存在します。

以下は React でのファイルアップロード実装の典型例です。

typescript// React でのファイルアップロードコンポーネント例
import React, { useState, useCallback } from 'react';

interface FileUploadProps {
  onUploadComplete: (result: any) => void;
}

const FileUpload: React.FC<FileUploadProps> = ({ onUploadComplete }) => {
  const [file, setFile] = useState<File | null>(null);
  const [uploading, setUploading] = useState(false);
  const [progress, setProgress] = useState(0);
  const [error, setError] = useState<string | null>(null);

  const handleFileChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
    const selectedFile = event.target.files?.[0];
    if (selectedFile) {
      setFile(selectedFile);
      setError(null);
    }
  }, []);

  const handleUpload = useCallback(async () => {
    if (!file) return;
    
    setUploading(true);
    setError(null);
    
    // アップロード処理...
  }, [file]);

  return (
    <div>
      <input type="file" onChange={handleFileChange} />
      <button onClick={handleUpload} disabled={uploading}>
        {uploading ? 'アップロード中...' : 'アップロード'}
      </button>
      {/* プログレスバーとエラー表示 */}
    </div>
  );
};

このように、シンプルなファイルアップロードでも多くの状態管理とイベントハンドリングが必要になります。

プログレスバーやエラーハンドリングの複雑性

ファイルアップロードでは、ユーザビリティ向上のためプログレスバーやエラーハンドリングが重要です。しかし、従来の手法では以下のような複雑な実装が必要でした。

javascript// プログレスバーの実装例
const xhr = new XMLHttpRequest();

xhr.upload.addEventListener('progress', (event) => {
  if (event.lengthComputable) {
    const percentComplete = (event.loaded / event.total) * 100;
    updateProgressBar(percentComplete);
  }
});

xhr.addEventListener('load', () => {
  if (xhr.status === 200) {
    handleSuccess(xhr.responseText);
  } else {
    handleError(`HTTP ${xhr.status}: ${xhr.statusText}`);
  }
});

xhr.addEventListener('error', () => {
  handleError('ネットワークエラーが発生しました');
});

xhr.addEventListener('timeout', () => {
  handleError('アップロードがタイムアウトしました');
});

このように、適切なユーザーフィードバックを提供するには、多くのイベントリスナーと状態管理が必要でした。

複数ファイル対応時の状態管理

複数ファイルの同時アップロードでは、各ファイルの進捗状況、エラー状態、完了状態を個別に管理する必要があります。

以下の図は、複数ファイルアップロード時の状態管理の複雑さを示しています。

mermaidstateDiagram-v2
    [*] --> 選択待ち
    選択待ち --> ファイル選択中: ファイル追加
    ファイル選択中--> アップロード準備: 全選択完了
    アップロード準備 --> アップロード中: 開始
    アップロード中 --> 個別進捗管理: 並列処理
    個別進捗管理 --> 完了: 全件成功
    個別進捗管理 --> エラー処理: 一部失敗
    エラー処理 --> 再試行: ユーザー操作
    再試行 --> アップロード中

従来の JavaScript では、この複雑な状態遷移を適切に管理することが大きな負担となっていました。

図で理解できる要点：

複数ファイルでは各ファイルごとに独立した状態管理が必要
エラー処理と再試行機能の実装が複雑
並列処理による予期しない状態遷移への対応が困難

解決策

htmx を用いたシンプルなファイルアップロード

htmx では、HTML 属性を使って宣言的にファイルアップロード機能を実装できます。複雑な JavaScript コードや状態管理は一切不要で、サーバーサイドからの HTML レスポンスによって UI を更新できます。

以下は最もシンプルな htmx ファイルアップロードの実装例です。

html<!-- 基本的な htmx ファイルアップロードフォーム -->
<form hx-post="/upload" 
      hx-target="#upload-result" 
      hx-encoding="multipart/form-data">
    <input type="file" name="file" required>
    <button type="submit">アップロード</button>
</form>

<div id="upload-result">
    <!-- アップロード結果がここに表示されます -->
</div>

このシンプルな HTML だけで、ファイルアップロード機能が完全に動作します。hx-post でアップロード先を指定し、hx-target で結果の表示先を指定するだけです。

hx-post と hx-encoding の活用

htmx でファイルアップロードを実装する際の核となる属性が hx-post と hx-encoding です。

html<!-- htmx 属性の詳細設定例 -->
<form hx-post="/api/upload" 
      hx-target="#result-area"
      hx-encoding="multipart/form-data"
      hx-indicator="#loading-spinner">
    
    <input type="file" 
           name="uploadFile" 
           accept="image/*,.pdf,.doc,.docx" 
           required>
    
    <button type="submit" class="upload-btn">
        ファイルをアップロード
    </button>
</form>

各属性の役割は以下の通りです。

属性	機能	説明
`hx-post`	HTTP メソッド指定	ファイルアップロード先の URL を指定
`hx-encoding`	エンコーディング	`multipart/form-data` でファイルデータを送信
`hx-target`	レスポンス表示先	サーバーからの HTML レスポンスを表示する要素
`hx-indicator`	ローディング表示	アップロード中に表示するローディング要素

hx-target によるレスポンス表示

hx-target 属性を使うことで、サーバーからのレスポンスを指定した要素に自動的に挿入できます。これにより、アップロード結果の表示やエラーメッセージの表示が簡単に実現できます。

html<!-- レスポンス表示エリアの設定 -->
<div id="upload-status" class="upload-status">
    <p>ファイルを選択してアップロードしてください</p>
</div>

<form hx-post="/upload" 
      hx-target="#upload-status"
      hx-encoding="multipart/form-data">
    <input type="file" name="file">
    <button type="submit">アップロード開始</button>
</form>

サーバーサイドでは、アップロード結果に応じて適切な HTML を返すだけです。

javascript// Express.js でのサーバーサイド実装例
app.post('/upload', upload.single('file'), (req, res) => {
    if (req.file) {
        res.send(`
            <div class="success">
                <h3>✅ アップロード完了</h3>
                <p>ファイル名: ${req.file.originalname}</p>
                <p>サイズ: ${(req.file.size / 1024).toFixed(2)} KB</p>
            </div>
        `);
    } else {
        res.status(400).send(`
            <div class="error">
                <h3>❌ アップロード失敗</h3>
                <p>ファイルが選択されていません</p>
            </div>
        `);
    }
});

以下の図は、htmx を使った場合のデータフローを示しています。

mermaidsequenceDiagram
    participant U as ユーザー
    participant F as htmx フォーム
    participant S as サーバー
    participant D as DOM

    U->>F: ファイル選択 & 送信
    F->>S: POST /upload (multipart/form-data)
    S->>S: ファイル処理
    S->>F: HTML レスポンス
    F->>D: hx-target 要素を更新
    D->>U: 結果表示

このように、htmx では宣言的な記述だけで完全なファイルアップロード機能を実現できます。

図で理解できる要点：

ユーザー操作からレスポンス表示まで自動化される
サーバーは HTML を返すだけでフロントエンド更新が完了
複雑な DOM 操作や状態管理が一切不要

具体例

単一ファイルアップロードの実装

最もシンプルな単一ファイルアップロードから始めましょう。以下は完全に動作する実装例です。

まず、HTML 側の実装です。

html<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>htmx ファイルアップロード</title>
    <script src="https://unpkg.com/htmx.org@1.9.10"></script>
    <style>
        .upload-container {
            max-width: 500px;
            margin: 50px auto;
            padding: 20px;
            border: 1px solid #ddd;
            border-radius: 8px;
        }
        
        .file-input {
            margin: 10px 0;
            padding: 10px;
            width: 100%;
        }
        
        .upload-btn {
            background: #007bff;
            color: white;
            padding: 10px 20px;
            border: none;
            border-radius: 4px;
            cursor: pointer;
        }
    </style>
</head>
<body>
    <div class="upload-container">
        <h2>ファイルアップロード</h2>
        
        <form hx-post="/upload" 
              hx-target="#result"
              hx-encoding="multipart/form-data">
            
            <input type="file" 
                   name="file" 
                   class="file-input"
                   accept=".jpg,.jpeg,.png,.gif,.pdf,.txt"
                   required>
            
            <button type="submit" class="upload-btn">
                アップロード
            </button>
        </form>
        
        <div id="result" style="margin-top: 20px;">
            <!-- アップロード結果がここに表示されます -->
        </div>
    </div>
</body>
</html>

次に、Node.js + Express でのサーバーサイド実装です。

javascript// server.js - Express サーバーの設定
const express = require('express');
const multer = require('multer');
const path = require('path');
const fs = require('fs');

const app = express();
const port = 3000;

// アップロードディレクトリの設定
const uploadDir = './uploads';
if (!fs.existsSync(uploadDir)) {
    fs.mkdirSync(uploadDir);
}

ファイルストレージの設定を行います。

javascript// multer の設定
const storage = multer.diskStorage({
    destination: function (req, file, cb) {
        cb(null, uploadDir);
    },
    filename: function (req, file, cb) {
        // ファイル名の重複を避けるためタイムスタンプを追加
        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
        cb(null, file.fieldname + '-' + uniqueSuffix + path.extname(file.originalname));
    }
});

const upload = multer({ 
    storage: storage,
    limits: {
        fileSize: 5 * 1024 * 1024 // 5MB制限
    },
    fileFilter: function (req, file, cb) {
        // ファイル形式の検証
        const allowedTypes = /jpeg|jpg|png|gif|pdf|txt/;
        const extname = allowedTypes.test(path.extname(file.originalname).toLowerCase());
        const mimetype = allowedTypes.test(file.mimetype);
        
        if (mimetype && extname) {
            return cb(null, true);
        } else {
            cb(new Error('許可されていないファイル形式です'));
        }
    }
});

アップロード処理のルートを実装します。

javascript// 静的ファイルの提供
app.use(express.static('public'));

// ファイルアップロードのルート
app.post('/upload', upload.single('file'), (req, res) => {
    try {
        if (!req.file) {
            return res.status(400).send(`
                <div style="padding: 15px; background: #f8d7da; color: #721c24; border-radius: 4px;">
                    <h4>❌ エラー</h4>
                    <p>ファイルが選択されていません。</p>
                </div>
            `);
        }

        // アップロード成功時のレスポンス
        res.send(`
            <div style="padding: 15px; background: #d4edda; color: #155724; border-radius: 4px;">
                <h4>✅ アップロード完了</h4>
                <p><strong>ファイル名:</strong> ${req.file.originalname}</p>
                <p><strong>サイズ:</strong> ${(req.file.size / 1024).toFixed(2)} KB</p>
                <p><strong>保存先:</strong> ${req.file.filename}</p>
                <button hx-post="/upload/reset" hx-target="#result" 
                        style="margin-top: 10px; padding: 5px 15px; background: #007bff; color: white; border: none; border-radius: 3px;">
                    新しいファイルをアップロード
                </button>
            </div>
        `);
    } catch (error) {
        res.status(500).send(`
            <div style="padding: 15px; background: #f8d7da; color: #721c24; border-radius: 4px;">
                <h4>❌ サーバーエラー</h4>
                <p>アップロード中にエラーが発生しました。</p>
            </div>
        `);
    }
});

// リセット用のルート
app.post('/upload/reset', (req, res) => {
    res.send('<p style="color: #666;">新しいファイルを選択してアップロードしてください。</p>');
});

app.listen(port, () => {
    console.log(`サーバーが http://localhost:${port} で起動しました`);
});

この実装により、わずかな HTML 属性の設定だけで完全なファイルアップロード機能が動作します。

複数ファイルアップロードの実装

複数ファイルの同時アップロードも、htmx では簡単に実現できます。HTML の multiple 属性を追加するだけです。

html<!-- 複数ファイルアップロード対応フォーム -->
<form hx-post="/upload/multiple" 
      hx-target="#multiple-result"
      hx-encoding="multipart/form-data">
    
    <label for="files">複数ファイルを選択:</label>
    <input type="file" 
           id="files"
           name="files" 
           multiple
           accept="image/*,.pdf,.txt"
           class="file-input">
    
    <button type="submit" class="upload-btn">
        すべてアップロード
    </button>
</form>

<div id="multiple-result" style="margin-top: 20px;">
    <p>複数のファイルを選択してアップロードできます。</p>
</div>

サーバーサイドでの複数ファイル処理は以下のように実装します。

javascript// 複数ファイルアップロードの処理
app.post('/upload/multiple', upload.array('files', 10), (req, res) => {
    try {
        if (!req.files || req.files.length === 0) {
            return res.status(400).send(`
                <div style="padding: 15px; background: #f8d7da; color: #721c24; border-radius: 4px;">
                    <h4>❌ エラー</h4>
                    <p>ファイルが選択されていません。</p>
                </div>
            `);
        }

        // アップロードされたファイルの情報を生成
        const fileList = req.files.map(file => `
            <li style="margin: 5px 0; padding: 8px; background: #f8f9fa; border-radius: 3px;">
                <strong>${file.originalname}</strong> 
                (${(file.size / 1024).toFixed(2)} KB)
                <span style="color: #28a745;">✅ 完了</span>
            </li>
        `).join('');

        res.send(`
            <div style="padding: 15px; background: #d4edda; color: #155724; border-radius: 4px;">
                <h4>✅ 全ファイルアップロード完了</h4>
                <p><strong>アップロード数:</strong> ${req.files.length} ファイル</p>
                <ul style="margin: 10px 0; padding-left: 0; list-style: none;">
                    ${fileList}
                </ul>
                <button hx-post="/upload/reset" hx-target="#multiple-result" 
                        style="margin-top: 10px; padding: 5px 15px; background: #007bff; color: white; border: none; border-radius: 3px;">
                    新しいファイルをアップロード
                </button>
            </div>
        `);
    } catch (error) {
        res.status(500).send(`
            <div style="padding: 15px; background: #f8d7da; color: #721c24; border-radius: 4px;">
                <h4>❌ サーバーエラー</h4>
                <p>アップロード中にエラーが発生しました。</p>
            </div>
        `);
    }
});

プログレスバー付きアップロード

htmx では hx-indicator 属性を使って、アップロード中のローディング表示を簡単に実装できます。

html<!-- プログレスバー付きアップロードフォーム -->
<form hx-post="/upload/progress" 
      hx-target="#progress-result"
      hx-indicator="#loading"
      hx-encoding="multipart/form-data">
    
    <input type="file" 
           name="file" 
           class="file-input"
           required>
    
    <button type="submit" class="upload-btn">
        アップロード開始
    </button>
</form>

<!-- ローディングインジケーター -->
<div id="loading" class="htmx-indicator" style="margin: 20px 0;">
    <div style="padding: 15px; background: #e3f2fd; border-radius: 4px; text-align: center;">
        <div class="spinner" style="
            border: 4px solid #f3f3f3;
            border-top: 4px solid #2196f3;
            border-radius: 50%;
            width: 30px;
            height: 30px;
            animation: spin 1s linear infinite;
            margin: 0 auto 10px;
        "></div>
        <p style="margin: 0; color: #1976d2;">アップロード中...</p>
    </div>
</div>

<div id="progress-result"></div>

<style>
@keyframes spin {
    0% { transform: rotate(0deg); }
    100% { transform: rotate(360deg); }
}

.htmx-indicator {
    display: none;
}

.htmx-request .htmx-indicator {
    display: block;
}
</style>

より詳細なプログレスバーを実装する場合は、htmx の hx-on 属性を使用できます。

html<!-- 詳細プログレスバー付きフォーム -->
<form hx-post="/upload/detailed-progress" 
      hx-target="#detailed-result"
      hx-encoding="multipart/form-data"
      hx-on="htmx:xhr:progress: 
        const progress = Math.round((event.detail.loaded / event.detail.total) * 100);
        document.getElementById('progress-bar-fill').style.width = progress + '%';
        document.getElementById('progress-text').textContent = progress + '%';
      ">
    
    <input type="file" name="file" required>
    <button type="submit">詳細プログレス付きアップロード</button>
</form>

<!-- プログレスバー表示エリア -->
<div id="progress-container" style="margin: 20px 0; display: none;">
    <div style="background: #f0f0f0; border-radius: 10px; overflow: hidden;">
        <div id="progress-bar-fill" 
             style="height: 20px; background: #4caf50; width: 0%; transition: width 0.3s;">
        </div>
    </div>
    <p id="progress-text" style="text-align: center; margin: 5px 0;">0%</p>
</div>

<div id="detailed-result"></div>

ドラッグ&ドロップ対応

htmx と組み合わせてドラッグ&ドロップ機能を実装することも可能です。少しの JavaScript を追加するだけで実現できます。

html<!-- ドラッグ&ドロップ対応アップロードエリア -->
<div id="drop-zone" style="
    border: 2px dashed #ccc;
    border-radius: 8px;
    padding: 40px;
    text-align: center;
    margin: 20px 0;
    transition: border-color 0.3s;
">
    <p>ファイルをここにドラッグ&ドロップするか、クリックして選択してください</p>
    
    <form id="drop-form" 
          hx-post="/upload/drop" 
          hx-target="#drop-result"
          hx-encoding="multipart/form-data">
        
        <input type="file" 
               id="drop-file-input" 
               name="file" 
               style="display: none;">
        
        <button type="button" 
                onclick="document.getElementById('drop-file-input').click()"
                class="upload-btn">
            ファイルを選択
        </button>
    </form>
</div>

<div id="drop-result"></div>

ドラッグ&ドロップの JavaScript 実装です。

javascript// ドラッグ&ドロップ機能の実装
document.addEventListener('DOMContentLoaded', function() {
    const dropZone = document.getElementById('drop-zone');
    const fileInput = document.getElementById('drop-file-input');
    const form = document.getElementById('drop-form');

    // ドラッグオーバー時のスタイル変更
    dropZone.addEventListener('dragover', function(e) {
        e.preventDefault();
        dropZone.style.borderColor = '#007bff';
        dropZone.style.backgroundColor = '#f8f9fa';
    });

    // ドラッグリーブ時のスタイルリセット
    dropZone.addEventListener('dragleave', function(e) {
        e.preventDefault();
        dropZone.style.borderColor = '#ccc';
        dropZone.style.backgroundColor = 'transparent';
    });

    // ファイルドロップ時の処理
    dropZone.addEventListener('drop', function(e) {
        e.preventDefault();
        dropZone.style.borderColor = '#ccc';
        dropZone.style.backgroundColor = 'transparent';

        const files = e.dataTransfer.files;
        if (files.length > 0) {
            fileInput.files = files;
            // htmx でフォーム送信をトリガー
            htmx.trigger(form, 'submit');
        }
    });

    // ファイル選択時の自動アップロード
    fileInput.addEventListener('change', function() {
        if (fileInput.files.length > 0) {
            htmx.trigger(form, 'submit');
        }
    });
});

以下の図は、ドラッグ&ドロップアップロードの処理フローを示しています。

mermaidflowchart TD
    A[ユーザーがファイルをドラッグ] --> B[ドロップゾーンに移動]
    B --> C[dragover イベント発生]
    C --> D[スタイル変更: ボーダー色変更]
    D --> E[ファイルドロップ]
    E --> F[drop イベント発生]
    F --> G[ファイルを input に設定]
    G --> H[htmx フォーム送信トリガー]
    H --> I[サーバーへアップロード]
    I --> J[結果表示]

このように、htmx と最小限の JavaScript を組み合わせることで、モダンなドラッグ&ドロップアップロード機能を簡単に実装できます。

図で理解できる要点：