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

チェックボックス

hc-checkbox は標準の <input type="checkbox"> に適用します。土台の input はネイティブの挙動をすべて保ちます — Space で切り替え、 value / name はフォーム送信に参加し、スクリーンリーダーはチェック ボックスとして報告します。appearance: none で置き換わるのは描画 だけです。

基本の HTML

Section titled “基本の HTML”

.hc-checkbox-label は、input とそのテキストをまとめてクリック挙動を 伝播する薄い inline-flex ヘルパーです。素の <input class="hc-checkbox"> を別の <label for> 要素と並べても 使えます。

バリアント

Section titled “バリアント”

data-variant は、デフォルト以外のチェック色として success、 warning、error を受け付けます。デフォルト(省略)のバリアントは アクティブなカラーテーマの primary の塗りを使います。

サイズ

Section titled “サイズ”

data-size は sm、md(デフォルト)、lg を受け付けます。 data-density とは独立です — サイズは密度対応のデフォルトサイズを 上書きするのではなく、専用の --hc-checkbox-{sm,lg}-size 変数を設定 するため、data-size="sm" でオプトインしたコントロールはどの密度階層 でも 14 px のままです。

data-size 外形寸法
sm 0.875rem(14 px)
md 1.125rem(18 px)— デフォルト
lg 1.375rem(22 px)

状態

Section titled “状態”

不確定状態(JS で input.indeterminate = true を設定)は、チェック マークの代わりに小さな横棒として描画されます。

真偽値フォームフィールドとして

Section titled “真偽値フォームフィールドとして”

未チェックのチェックボックスは何も送信しません — フォーム POST から 宣言済みの真偽値をバインドするサーバには、false ではなくフィールドの 不在が見えます。これが公認の真偽値フィールドパターンです: 値を 保証する隠し input を、同じ name の下でチェックボックスと対にし、 hc-field の一連の マークアップの中に置きます。素のマークアップなので、コード ジェネレーターは真偽値カラムに対してそのまま出力でき、 マークアップのバージョニングポリシーの 下で安定しています。

Deactivated accounts are hidden from search.

契約はこうです: 未チェックは active=false を送信し、チェック済みは active=false&active=true を送信して、サーバは最後の出現を バインドします — 主要なフォームバインダーが従う規約です(Rails の check_box ヘルパーが長年やってきたやり方です)。隠し input は DOM で 先に置いてください。last-wins を機能させているのは文書順です。

どちらのラベルパターンを使うか

Section titled “どちらのラベルパターンを使うか”

hc-field の一連のマークアップの中では、上とまったく同じく hc-field__label + for を使います — ラベルの列が他のすべての フィールド型と一貫します。.hc-checkbox-label のクラスターは、 フィールド外のチェックボックス — 単独の同意行や、 <fieldset class="hc-field"> グループの項目 — のためのものです。

スイッチ変種

Section titled “スイッチ変種”

hc-switch は文字通り <input type="checkbox" role="switch"> です — フォーム送信への参加は 同一なので、パターンはそのまま移植できます:

<div class="hc-field">
  <label class="hc-field__label" for="notify">Email notifications</label>
  <input type="hidden" name="notify" value="false">
  <input class="hc-switch" id="notify" name="notify" type="checkbox" role="switch" value="true">
</div>

フィールドエラー

Section titled “フィールドエラー”

field-errors レシピは そのまま機能します: data-field="active" を持つサーバの項目は同名 グループを解決し、メッセージ、aria-invalid、フォーカス、編集時 クリアをチェックボックスへ配線します — グループの隠しメンバーは スキップされるため、重複した name が振り分けを混乱させることは ありません。

これらの主張は、まさにこのマークアップに対するブラウザテスト (test-browser/booleanfield.spec.mjs)で固定されており、生成コード にとってパターンは安定しています。

すべて選択

Section titled “すべて選択”

チェックリスト — 権限マトリクス、出力する列、通知のまとめ — には、 全部をまとめて設定する 1 つのボックスが欲しくなります。マスターの チェックボックスに data-hc-select-all="<グループの id>" を付け、 name は付けないでください。あとは installSelectAll() が やります:

Permissions
  • マスター → メンバー: チェック / 解除すると、グループ(その id を 持つ要素。マスターはその中にあっても外にあってもよい)内の有効な チェックボックスすべてを設定します。
  • メンバー → マスター: 全部チェック → checked、ゼロ → クリア、 一部 → indeterminate。インストール時(サーバが描画した checked から)、変更のたび、そしてグループ内の htmx スワップの後にも同期 するので、後から届いた行も数に入ります。
  • マスターは決して送信されません。name を持たず(あれば ビヘイビアが取り除きます)、サーバはネイティブのフォーム直列化で メンバーだけを見ます — ビヘイビアなしとまったく同じで、それが no-JS 経路でもあります: マスターはただの箱になり、メンバーは そのまま動きます。
  • メンバーをプログラムで設定しても change は発火しません(ネイティブ の意味論)。マスター自身の change がグループを 1 回バブルするので、 fieldset の data-hc-submit-on-change はイベントを 1 つだけ見ます。

hc-datagrid の行には これは不要です — グリッドのヘッダーチェックボックスは組み込みです。

htmx での利用

Section titled “htmx での利用”

hc-checkbox はネイティブのチェックボックスと同様にフォーム送信へ 参加します。サーバサイドバリデーションのフィードバックには、 aria-invalid="true" を設定した input を返します。周囲のメッセージも スタイルし直すには hc-field と組み合わせて ください。

<label class="hc-checkbox-label">
  <input
    class="hc-checkbox"
    type="checkbox"
    name="terms"
    required
    data-hx-post="/preferences/toggle"
    data-hx-trigger="change">
  I accept the terms
</label>

アクセシビリティ

Section titled “アクセシビリティ”
  • このコンポーネントはネイティブの <input type="checkbox"> を保つ ため、支援技術は正しく読み上げ、Space で切り替わります。
  • input には常にラベルを関連付けてください。最も簡単なのは両方を <label class="hc-checkbox-label"> で包むパターンです。そうでなければ input の id に紐づく別の <label for> を使います。
  • バリデーションエラーでは input に aria-invalid="true" を設定し、 エラーメッセージがあれば aria-describedby と対にしてください。
  • コントロールが操作不能であるべきときはネイティブの disabled 属性を 選び、フォーカス可能であり続けるべきときだけ aria-disabled="true" を使ってください。
  • フォーカスのアウトラインを消さないでください。このコンポーネントは デフォルトのアウトラインを、--hc-color-focus-ring で駆動される 見える box-shadow リングに置き換えています。

テーマ用トークン

Section titled “テーマ用トークン”

component トークン(component.tokens.json):

トークンパス 用途
checkbox.size 外形寸法(正方形)。
checkbox.border / border-width / radius 未チェック状態の枠線。
checkbox.bg 未チェック状態の背景。
checkbox.checked-bg / checked-border デフォルトバリアントのチェック色。
checkbox.success-checked-bg / success-checked-border data-variant="success"。
checkbox.warning-checked-bg / warning-checked-border data-variant="warning"。
checkbox.error-checked-bg / error-checked-border data-variant="error"。
checkbox.sm.size / lg.size data-size="sm" / "lg" の専用サイズ。
checkbox.error-border aria-invalid="true" 時の枠線。
checkbox.disabled-bg 無効時の背景。
checkbox.label-gap input とテキストの間のギャップ。

CSS 変数

Section titled “CSS 変数”
生成される CSS 変数を表示
--hc-checkbox-size
--hc-checkbox-border-width | -border | -radius
--hc-checkbox-bg
--hc-checkbox-checked-bg | -checked-border
--hc-checkbox-success-checked-bg | -success-checked-border
--hc-checkbox-warning-checked-bg | -warning-checked-border
--hc-checkbox-error-checked-bg | -error-checked-border
--hc-checkbox-sm-size | -lg-size
--hc-checkbox-error-border
--hc-checkbox-disabled-bg
--hc-checkbox-label-gap
--hc-color-focus-ring
--hc-color-error

関連

Section titled “関連”

レシピでの利用: フィールドエラー · ミューテーションフォーム