コンテンツにスキップ
Hypermedia Components

Plain HTML

Hypermedia Components の本質は静的な UI キットです: CSS ファイル 1 つ、 小さな JS モジュール 1 つ、任意のマクロエントリ 1 つ。フレームワーク ガイドはテンプレートエンジン固有の糊を扱います。このページは、ただ HTML を 配信するだけのプロジェクトに必要な最小限を扱います。

必要なもの

Section titled “必要なもの”
hc.css                # バンドル済み CSS(現行の数値はバンドルサイズ参照)
hc.behaviors.min.js   # 自己完結のビヘイビアバンドル
macros/index.min.js   # 任意 — <hc-confirm-action> / <hc-live-search> カスタム要素用(gzip 約 1 KB)
htmx.min.js           # 自分で用意

最初の 3 つは npm install @hypermedia-components/core して node_modules/@hypermedia-components/core/dist/ からコピーするか、 GitHub Releases からダウンロードできます。htmx は htmx.org からダウンロードします。

ファイル配置

Section titled “ファイル配置”

<link> と <script> タグの URL が解決される限り、どんな配置でも 構いません。よくある形:

public/                     # または wwwroot/, static/ など
  index.html
  assets/
    hc/
      hc.css
      hc.behaviors.min.js
      macros/
        index.min.js          # 自己完結 — 兄弟ファイル不要
    htmx.min.js

最小のレイアウトファイル

Section titled “最小のレイアウトファイル”
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My app</title>
  <link rel="stylesheet" href="/assets/hc/hc.css">
  <script defer src="/assets/htmx.min.js"></script>
  <script type="module" src="/assets/hc/hc.behaviors.min.js"></script>
</head>
<body>
  <main>
    <!-- your content -->
  </main>


  <!-- One toast region near the end of body. -->
  <div class="hc-toast-region"
       data-hc-toast-region
       role="region"
       aria-label="Notifications"></div>
</body>
</html>

インテグレーションはこれで全部です。hc.behaviors.min.js が DOMContentLoaded ですべてのデフォルトビヘイビアを自己インストール するため、[data-hc-confirm]、hc:toast イベント、各種 data-hc-close-* / data-hc-remote-dialog-root 属性は追加の配線なしで 機能します。

実行可能な例

Section titled “実行可能な例”

以下は、ボタンを描画し、クリックで POST /items を送り、成功時に トーストを表示する完全なページです。index.html として保存し、記載の アセットを /assets/ 配下に置いて、ブラウザで開いてください(小さな 静的サーバが必要です — python -m http.server や npx serve など。 htmx は XHR リクエストを行い、ほとんどのブラウザは file:// でそれを ブロックするためです)。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>HC + htmx demo</title>
  <link rel="stylesheet" href="/assets/hc/hc.css">
  <script defer src="/assets/htmx.min.js"></script>
  <script type="module" src="/assets/hc/hc.behaviors.min.js"></script>
</head>
<body style="padding: 2rem; max-inline-size: 32rem; margin: 0 auto;">


  <h1>Hello hypermedia</h1>


  <span class="hc-action">
    <button
      class="hc-button"
      data-variant="primary"
      type="button"
      data-hx-post="/items"
      data-hx-target="#items"
      data-hx-disabled-elt="this"
      data-hx-indicator="closest .hc-action">
      Save
    </button>
    <span class="hc-spinner htmx-indicator" aria-hidden="true"></span>
  </span>


  <ul id="items" style="margin-block-start: 1.5rem;"></ul>


  <div class="hc-toast-region"
       data-hc-toast-region
       role="region"
       aria-label="Notifications"></div>


</body>
</html>

より充実した遊び場(全コンポーネント、全レシピ、htmx ラウンドトリップ) には、リポジトリをクローンして examples/plain-html/ プロジェクトを実行してください — 上と同じ形で、すべてのコンポーネントが 並んでいます。

テーマ切り替え

Section titled “テーマ切り替え”

hc.css はライトとダークのバリアントをすでに宣言しています (トークンは同梱済み — 追加のスタイルシートは不要です)。 <html> 要素の data-theme で切り替えます:

<html lang="en" data-theme="dark">…</html>
// One-liner toggle.
document.documentElement.dataset.theme =
  document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';

訪問をまたいで保持したい場合は、選択を localStorage に永続化して ください。

密度

Section titled “密度”

data-density は、data-theme が色を制御するのと同じやり方で 詰まり具合を制御します:

<html data-density="compact">…</html>

デフォルトは comfortable です。値とライブプレビューは トークン → 密度を参照して ください。

htmx なしで

Section titled “htmx なしで”

CSS コンポーネントは、htmx なし・JS ビヘイビアなしでも使えます。 ボタン、インプット、フィールド、ダイアログ、ポップオーバー、アラート、 バッジ、ツールバー、ページネーション、テーブルはすべて hc.css だけで 正しく描画されます。インタラクティビティの層はオプトインです。

<link rel="stylesheet" href="/assets/hc/hc.css">


<button class="hc-button" data-variant="primary">Save</button>
<input class="hc-input" type="text" placeholder="Search…">

CSS のみのコンポーネントはすべて コンポーネントセクションに ドキュメントがあります。

関連

Section titled “関連”