ポップオーバー
ポップオーバーは、開示要素の周りに浮かぶ非モーダルダイアログです。通常、何かの上にリッチコンテンツを追加表示するために使用されます。
インストール
npx nextui-cli@latest add popover
上記のコマンドは個別のインストール専用です。 @nextui-org/react
がグローバルにインストール済みの場合は、このステップをスキップできます。
インポート
NextUI は、ポップオーバー関連の 3 つのコンポーネントをエクスポートします。
- Popover: ポップオーバーを表示するためのメインコンポーネント。
- PopoverTrigger: ポップオーバーをトリガーするコンポーネント。
- PopoverContent: ポップオーバーのコンテンツを格納するコンポーネント。
使い方
矢印付き
色
配置
オフセット
制御
タイトル Props
ポップオーバーが支援技術に対して正しいタイトルを公開することを確実にするには、PopoverContent
コンポーネントで titleProps
プロパティを使用する必要があります。このプロパティを使用するには、子として関数を渡す必要があります。
フォーム付き
Popover
は、ポップオーバーコンテンツ内のフォーカスを処理します。つまり、問題なくフォーム要素でポップオーバーを使用できます。ポップオーバーが閉じると、フォーカスはトリガーに戻ります。
注: ポップオーバーが開いたときにフォーカスを当てるために、最初の
Input
コンポーネントにautoFocus
プロパティを追加できます。
背景
Popover
コンポーネントには、ポップオーバーの背面に背景を表示するためのbackdrop
プロパティがあります。背景は、transparent
、opaque
、またはblur
のいずれかになります。デフォルト値はtransparent
です。
カスタムモーション
Popoverは、motionProps
プロパティを提供し、enter
/ exit
アニメーションをカスタマイズできます。
Framer motion variantsの詳細については、こちらをご覧ください。
カスタムトリガー
スロット
- base:メインのポップオーバースロットで、ポップオーバーコンテンツをラップし、擬似要素(::before)として矢印を含みます。
- trigger:ポップオーバーのトリガースロットで、トリガーが正しく機能するように小さなスタイルが適用されています。
- backdrop:背景スロットで、背景スタイルが含まれています。
- content:コンテンツスロットで、ポップオーバーコンテンツが含まれています。
カスタムスタイル
コンポーネントスロットにカスタムTailwind CSSクラスを渡すことで、Popover
コンポーネントをカスタマイズできます。
データ属性
Popover
には、PopoverContent
要素に次の属性があります。
- data-open:ポップオーバーが開いている場合。ポップオーバーの状態に基づきます。
- data-placement:ポップオーバーの配置。
placement
プロパティに基づきます。矢印要素はこの属性に基づいて配置されます。 - data-focus:ポップオーバーがフォーカスされている場合。useFocusRingに基づきます。
- data-focus-visible:キーボードでポップオーバーにフォーカスされている場合。useFocusRingに基づきます。
アクセシビリティ
- トリガーとポップオーバーは、ARIAを介して意味的に自動的に関連付けられます。
- ポップオーバーが開いている間、ポップオーバーの外側のコンテンツは支援技術から隠されます。
- ポップオーバーは、外部とのインタラクション時、またはEscapeキーを押すと閉じます。
- フォーカスはマウント時にポップオーバーに移動し、アンマウント時にトリガー要素に戻ります。
- ポップオーバーはトリガー要素を基準に配置され、ブラウザウィンドウの端との重複を避けるために自動的に反転および調整されます。
- ポップオーバーの外側のスクロールは、意図せずにポップオーバーの位置を変更したり閉じたりしないように防止されます。
API
Popoverのプロパティ
属性 | 型 | 説明 | デフォルト |
---|---|---|---|
children* | ReactNode[] | ポップオーバーのコンテンツ。通常は、PopoverTrigger とPopoverContent です。 | - |
size | sm | md | lg | ポップオーバーコンテンツのフォントサイズ。 | md |
color | default | primary | secondary | success | warning | danger | ポップオーバーのカラーテーマ。 | default |
radius | none | sm | md | lg | full | ポップオーバーのボーダー半径。 | lg |
影 | none | sm | md | lg | ポップオーバーの影。 | lg |
背景 | transparent | opaque | blur | ポップオーバーの背景の種類。 | transparent |
配置 | PopoverPlacement | トリガー参照に対するポップオーバーの配置。 | 下 |
状態 | OverlayTriggerState | ポップオーバーの制御された状態。 オーバレイ状態を参照してください。 | - |
isOpen | boolean | ポップオーバーがデフォルトで開いているかどうか(制御)。 | - |
defaultOpen | boolean | ポップオーバーがデフォルトで開いているかどうか(非制御)。 | - |
offset(px) | number | 参照とポッパー間の距離またはマージン。オフセット修飾子を作成するために内部的に使用されます。 | 7 |
containerPadding(px) | number | 要素とその周囲のコンテナの間に適用される配置パディング。 | 12 |
crossOffset(px) | number | 要素とそのアンカー要素の間で、クロス軸に沿って適用される追加のオフセット。 | 0 |
triggerType | dialog | menu | listbox | tree | grid ; | トリガーによって開かれるポップオーバーのタイプ。 | dialog |
showArrow | boolean | ポップオーバーに矢印を表示するかどうか。 | false |
shouldFlip | boolean | ポップオーバーが境界領域からあふれそうになったときに、配置を変更して反転するかどうか。 | true |
triggerScaleOnOpen | boolean | ポップオーバーが開いているときに、トリガーを縮小するかどうか。 | true |
shouldBlockScroll | boolean | ポップオーバーの外側のスクロールをブロックするかどうか。 | false |
isKeyboardDismissDisabled | boolean | ポップオーバーを閉じるために Escape キーを押すことを無効にするかどうか。 | false |
shouldCloseOnBlur | boolean | フォーカスが失われたり、ポップオーバーの外に移動した場合に、ポップオーバーを閉じるかどうか。 | false |
motionProps | MotionProps | Framer Motionアニメーションを修正するためのプロパティ。独自の アニメーションを作成するには、variants API を使用します。 | |
portalContainer | HTMLElement | オーバレイポータルが配置されるコンテナ要素。 | document.body |
updatePositionDeps | any[] | ポップオーバーの位置更新を強制する依存関係。 | [] |
triggerRef | RefObject<HTMLElement> | ポップオーバーが位置を調整する基準となる要素のref。 | - |
scrollRef | RefObject<HTMLElement> | ポップオーバー内のスクロール可能な領域のref。 | overlayRef |
disableAnimation | boolean | ポップオーバーをアニメーション化するかどうか。 | false |
classNames | Record<"base"| "trigger"| "backdrop"| "content", string> | ポップオーバースロットのカスタムクラス名を設定できます。 | - |
ポップオーバーイベント
属性 | 型 | 説明 |
---|---|---|
onOpenChange | (isOpen: boolean) => void | ポップオーバーの開閉状態が変更されたときに呼び出されるハンドラー。 |
shouldCloseOnInteractOutside | (e: HTMLElement) => void | ユーザーがポップオーバー ref の外の引数要素を操作したときに、onClose を呼び出す必要がある場合は true を返します。これにより、ポップオーバーを閉じない要素とのインタラクションを除外できます。デフォルトでは、オーバレイ ref の外側でのインタラクションでは、常に onClose が呼び出されます。 |
onClose | () => void | ポップオーバーを閉じる必要があるときに呼び出されるハンドラー。 |
PopoverTrigger プロパティ
属性 | 型 | 説明 | デフォルト |
---|---|---|---|
children* | ReactNode | ポップオーバートリガーコンポーネント。渡された子要素がフォーカス可能であることを確認してください。ユーザーはキーボードを使用してタブで移動でき、ref を受け取ることができます。これはアクセシビリティにとって重要です。 | - |
PopoverContent プロパティ
属性 | 型 | 説明 | デフォルト |
---|---|---|---|
children | ReactNode | トリガーが押されたときに表示されるコンテンツ。 | - |
ポップオーバーのタイプ
ポップオーバーの配置
type PopoverPlacement =| "top"| "bottom"| "right"| "left"| "top-start"| "top-end"| "bottom-start"| "bottom-end"| "left-start"| "left-end"| "right-start"| "right-end";
Motion Props
export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/