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

スイッチ

hc-switch は標準の <input type="checkbox" role="switch"> に適用 します。土台の input はネイティブの挙動をすべて保ちます — Space で切り替え、値はフォーム送信に参加し、role の上書きにより スクリーンリーダーはスイッチとして読み上げます — 置き換わるのは appearance: none による見た目のクロームだけです。

別名: トグル、トグルスイッチ。

基本の HTML

Section titled “基本の HTML”

.hc-switch-label は、スイッチとそのテキストをまとめる inline-flex ヘルパーで、ラベルのクリックで input が切り替わります。

バリアント

Section titled “バリアント”

data-variant は、デフォルト以外のチェック状態の色味として success、warning、error を受け付けます — チェックボックスや ラジオと同じ 3 点セット です。デフォルト(省略)のバリアントは、アクティブなカラーテーマの primary の塗りを使います。

サイズ

Section titled “サイズ”

data-size は sm、md(デフォルト)、lg を受け付けます。

状態

Section titled “状態”

htmx での利用

Section titled “htmx での利用”

スイッチはネイティブのチェックボックスと同様にフォーム送信へ参加 します。即時トグルには change を待ち受けます:

<label class="hc-switch-label">
  <input
    class="hc-switch"
    type="checkbox"
    role="switch"
    name="notifications"
    data-hx-post="/preferences/notifications"
    data-hx-trigger="change">
  Email notifications
</label>

スイッチが素のフォーム POST の一部で、サーバが宣言済みの真偽値に バインドする場合、未チェックのスイッチは何も送信しないことを思い出して ください — 公認の真偽値フィールドパターン (同じ name の下に 隠し false + スイッチ true)を使います。 hc-switch にそのまま当てはまります。

スイッチ自体がアクション

Section titled “スイッチ自体がアクション”

フィーチャーフラグ、ユーザーごとの設定 — スイッチそのものが保存で、 Save ボタンはありません。スイッチごとに個別のリクエストを持たせる 代わりに、フォームを単位のまま保ち — mutating-form レシピ がすでに持っているもの(target、swap、422 の再描画)です — data-hc-submit-on-change で、変化した瞬間にスイッチにフォームを 送信させます:

<form method="post" action="/flags"
      data-hx-post="/flags" data-hx-target="closest .hc-card"
      data-hx-swap="outerHTML" data-hx-sync="this:replace">
  <label class="hc-switch-label">
    <input type="hidden" name="beta" value="false">
    <input class="hc-switch" type="checkbox" role="switch"
           name="beta" value="true" data-hc-submit-on-change>
    Beta features
  </label>
  <noscript><button class="hc-button" type="submit">Save</button></noscript>
</form>

change でビヘイビアは form.requestSubmit() を呼びます。制約検証が 走り、フォームの submit イベントが発火し、そこから htmx がリクエストを 引き受けます — つまり hx-sync、 ダーティガード、 CSRF ヘッダー、 data-hc-close-dialog-on-success がすべて、Save ボタンを押したときと まったく同じように効きます。属性は <fieldset> に置くこともできます。 子孫の change はそこまでバブルするので、設定グループがひとつの フォームとして送信されます。

ビヘイビアが一度だけ代わりに決めることが 2 つあります。自前の htmx verb を持つコントロール(上の data-hx-post の形)はそのまま、 hx-trigger にすでに change を含むフォームもそのまま — どちらも htmx が駆動しており、2 度目の送信は二重発火になるからです。 JavaScript なしではスイッチは自動送信しません。<noscript> の Save ボタンが no-JS 経路を正直に保ちます。

アクセシビリティ

Section titled “アクセシビリティ”
  • input には常にラベルを対にしてください。両方を <label class="hc-switch-label"> で包むか、id で関連付けた別の <label for> を使います。
  • role="switch" は、二値のオン / オフトグルのまさにその セマンティックな role です — 素のチェックボックスより選んで ください。スクリーンリーダーが「チェックボックス、チェック済み / 未チェック」ではなく「スイッチ、オン / オフ」と読み上げます。土台の 要素はフォームシリアライズのために <input type="checkbox"> の ままです。ARIA role の上書きは読み上げ方だけを変えます。
  • フォーカスのアウトラインを消さないでください。このコンポーネントは デフォルトのアウトラインを、--hc-color-focus-ring で駆動される 見える box-shadow リングに置き換えています。
  • つまみのスライドのトランジションは prefers-reduced-motion: reduce を尊重します — ユーザーがオプト アウトしていれば動きは抑制されます。

テーマ用トークン

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

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

トークンパス 用途
switch.width / height トラックの寸法。
switch.thumb-size 動くつまみの直径。
switch.padding つまみとトラック端の隙間。
switch.bg / thumb-bg オフ状態の色。
switch.checked-bg / checked-border デフォルトバリアントのオン状態。
switch.success-checked-bg / warning-checked-bg / error-checked-bg バリアントのオン状態。
switch.disabled-bg 無効時の背景。
switch.label-gap スイッチとテキストの間のギャップ。
switch.sm.* / lg.* 専用の sm / lg 上書き。

CSS 変数

Section titled “CSS 変数”
生成される CSS 変数を表示
--hc-switch-width | -height | -thumb-size | -padding
--hc-switch-border-width | -border
--hc-switch-bg | -thumb-bg
--hc-switch-checked-bg | -checked-border
--hc-switch-success-checked-bg | -warning-checked-bg | -error-checked-bg
--hc-switch-disabled-bg | -label-gap
--hc-switch-sm-width | -sm-height | -sm-thumb-size
--hc-switch-lg-width | -lg-height | -lg-thumb-size
--hc-color-focus-ring (inherited from data-color)

関連

Section titled “関連”
  • チェックボックス — 比喩が「オン / オフの切り替え」ではなく「同意 / オプトイン」のとき。
  • ラジオ — 小さな固定集合からの単一選択。