Popover

補足の説明や小さな操作を、必要な時に開いて表示します。

説明だけ・アイコンのみのトリガー
関連リンク・操作欄
短い入力・必須入力の検証
右寄せ・右から左の配置
長い見出し・長文・スクロール
処理中・エラー・無効状態
Popover内の補足・Dialog内の補足

共有設定の確認

補足を閉じても、この確認画面は開いたままです。

使いどころ

  • 用語の補足、関連するリンク、短い入力のように、必要な時だけ開いて見る内容に使います。背後の画面は操作できるままです。
  • 答えるまで先へ進ませない確認や必須の入力は Dialog を使います。
  • リンクや対象にホバーした時の概要は HoverCard、操作に添える一言の補足は Tooltip を使います。
  • 補助の操作を並べるだけなら DropdownMenu を使います。

使い方

標準のPopover API(popover="auto")で開閉する、モーダルでない白いパネル(1px #bbbbbb の枠、角丸5px、外へ約8pxの柔らかい影)です。開く操作とパネルはCSSのアンカーで結び、開く操作の下に揃えて置きます。id は画面内で一意にします。

PopoverController を popover として登録すると、CSSのアンカーに対応しない環境や、パネルが画面に収まらない時に位置を補い、画面の端から8pxの内側に収めます。スクロールと画面の大きさの変化にも追従します。

パネルは見出し・本文・操作欄に分けます。title を省略すると label を見出しにし、titleHidden で見出しを読み上げだけに残せます。見出しは12pxの黒い太字、description は見出しの下の灰色の説明、actions は下の操作欄です。見出しの行の末尾の角には、枠も面も持たない灰色の×を閉じる操作として置きます。size はパネルの幅の上限で、compact は16rem、default は20rem、wide は28remです。

align の end は、行の末尾側に置いた開く操作に揃えます。dir="rtl" では始端と末端が入れ替わります。

開く操作は icon・iconOnly・disabled・triggerVariant で変えられます。iconOnly の開く操作には tooltip で名前を出せます。

開くと見出しへフォーカスを移します。initialFocus を content にすると、本文の autofocus の欄へ移ります。パネルの外側を押す・Escape・閉じる操作で閉じます。パネルの中に別の Popover を開いても、元のパネルは開いたままです。

本文のフォームの送信やリンクの移動は、標準の振る舞いのまま利用側が扱います。JavaScriptなしでも標準のPopover APIで開閉し、CSSのアンカーに対応しない環境ではパネルを画面の中央に出します。

キーボード

Popoverのキーボード操作
キー動作
Enter / Space(開く操作)パネルを開き、見出し(initialFocus が content なら本文の autofocus の欄)へ移ります。
Escapeパネルを閉じ、開く操作へフォーカスを戻します。

アクセシビリティ

  • パネルは role="dialog" で、見出しを名前(aria-labelledby)、description を説明(aria-describedby)にします。見出しは tabindex="-1" で、Tabの巡回には入りません。
  • 開く操作は aria-haspopup="dialog"・aria-controls を持ちます。iconOnly の時は label を aria-label にします(icon が無ければinfoのアイコンを出します)。
  • tooltip で出す名前は見た目だけの補足で、aria-describedby には結び付けません。名前は aria-label で読み上げます。
  • 見出しの横の閉じる操作はアイコンだけなので、closeLabel を aria-label にします。閉じる操作とEscapeで閉じると、開く操作へフォーカスを戻します。

API

Popover

非モーダルの補足表示。開閉は標準Popover API、位置指定はCSSを優先する。

Popoverのprops
名前型既定値説明
id必須stringパネルのid。画面内で一意にする。開く操作のpopovertargetと、CSSのアンカー名の元になる。
label必須string開く操作の文言。iconOnlyの時はaria-labelとして読み上げる。
titlestringlabelパネルの見出し。省略するとlabelを使う。
descriptionstring見出しの下に置く短い説明。パネルの説明(aria-describedby)になる。
align"start" | "end""start"パネルを開く操作のどちらの端に揃えるか。
size"compact" | "default" | "wide""default"パネルの幅。compactは16rem、defaultは20rem、wideは28remを上限にする。
iconIconName開く操作の文言の前に置くアイコン。
iconOnlybooleanfalse開く操作をアイコンだけにする。iconが無ければinfoのアイコンを出す。
disabledboolean開く操作を押せなくする。
triggerVariantButtonProps["variant"]"secondary"開く操作の見た目。値の意味はButtonと同じ。
closeLabelstring"閉じる"見出しの横の閉じる操作の名前。
initialFocus"title" | "content""title"開いた時にフォーカスを移す先。titleは見出し(既定)。contentは中身のautofocusを付けた欄へ移り、開いてすぐ入力を始めるもの(EmojiPickerの検索欄など)に使う。
titleHiddenbooleanfalse見出しを読み上げだけに残し、画面には出さない。開く操作の名前で中身が分かる小さなパネルに使う。
tooltipbooleanfalseアイコンだけの開く操作に、ホバー時とフォーカス時の名前をTooltipで出す。既定は出さない。
actionsChildパネルの下の操作欄に並べる操作。
dir"ltr" | "rtl"文字の向き。rtlでは先頭と末尾が入れ替わる。
childrenChildパネルの本文。リンクや短いフォームを置ける。

登録するcontroller:popover(PopoverController)、tooltip(TooltipController)

読み込むCSS:layers.css、reset.css、tokens.css、base.css、layout.css、components/button.css、components/overlay.css、components/icon.css、components/popover.css、components/tooltip.css

IconName

値:Iconの見本

ButtonProps

Buttonのpropsと同じです。

コード

HTML
Hono JSX