ポップオーバー

ポップオーバーは、開示要素の周りに浮かぶ非モーダルダイアログです。通常、何かの上にリッチコンテンツを追加表示するために使用されます。


インストール

npx nextui-cli@latest add popover
上記のコマンドは個別のインストール専用です。 @nextui-org/react がグローバルにインストール済みの場合は、このステップをスキップできます。

インポート

NextUI は、ポップオーバー関連の 3 つのコンポーネントをエクスポートします。

  • Popover: ポップオーバーを表示するためのメインコンポーネント。
  • PopoverTrigger: ポップオーバーをトリガーするコンポーネント。
  • PopoverContent: ポップオーバーのコンテンツを格納するコンポーネント。

使い方

矢印付き

配置

オフセット

制御

タイトル Props

ポップオーバーが支援技術に対して正しいタイトルを公開することを確実にするには、PopoverContent コンポーネントで titleProps プロパティを使用する必要があります。このプロパティを使用するには、子として関数を渡す必要があります。

フォーム付き

Popover は、ポップオーバーコンテンツ内のフォーカスを処理します。つまり、問題なくフォーム要素でポップオーバーを使用できます。ポップオーバーが閉じると、フォーカスはトリガーに戻ります。

: ポップオーバーが開いたときにフォーカスを当てるために、最初の Input コンポーネントに autoFocus プロパティを追加できます。

背景

Popoverコンポーネントには、ポップオーバーの背面に背景を表示するためのbackdropプロパティがあります。背景は、transparentopaque、または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[]ポップオーバーのコンテンツ。通常は、PopoverTriggerPopoverContentです。-
sizesm | md | lgポップオーバーコンテンツのフォントサイズ。md
colordefault | primary | secondary | success | warning | dangerポップオーバーのカラーテーマ。default
radiusnone | sm | md | lg | fullポップオーバーのボーダー半径。lg
none | sm | md | lgポップオーバーの影。lg
背景transparent | opaque | blurポップオーバーの背景の種類。transparent
配置PopoverPlacementトリガー参照に対するポップオーバーの配置。
状態OverlayTriggerStateポップオーバーの制御された状態。 オーバレイ状態を参照してください。-
isOpenbooleanポップオーバーがデフォルトで開いているかどうか(制御)。-
defaultOpenbooleanポップオーバーがデフォルトで開いているかどうか(非制御)。-
offset(px)number参照とポッパー間の距離またはマージン。オフセット修飾子を作成するために内部的に使用されます。7
containerPadding(px)number要素とその周囲のコンテナの間に適用される配置パディング。12
crossOffset(px)number要素とそのアンカー要素の間で、クロス軸に沿って適用される追加のオフセット。0
triggerTypedialog | menu | listbox | tree | grid;トリガーによって開かれるポップオーバーのタイプ。dialog
showArrowbooleanポップオーバーに矢印を表示するかどうか。false
shouldFlipbooleanポップオーバーが境界領域からあふれそうになったときに、配置を変更して反転するかどうか。true
triggerScaleOnOpenbooleanポップオーバーが開いているときに、トリガーを縮小するかどうか。true
shouldBlockScrollbooleanポップオーバーの外側のスクロールをブロックするかどうか。false
isKeyboardDismissDisabledbooleanポップオーバーを閉じるために Escape キーを押すことを無効にするかどうか。false
shouldCloseOnBlurbooleanフォーカスが失われたり、ポップオーバーの外に移動した場合に、ポップオーバーを閉じるかどうか。false
motionPropsMotionPropsFramer Motionアニメーションを修正するためのプロパティ。独自の アニメーションを作成するには、variants API を使用します。
portalContainerHTMLElementオーバレイポータルが配置されるコンテナ要素。document.body
updatePositionDepsany[]ポップオーバーの位置更新を強制する依存関係。[]
triggerRefRefObject<HTMLElement>ポップオーバーが位置を調整する基準となる要素のref。-
scrollRefRefObject<HTMLElement>ポップオーバー内のスクロール可能な領域のref。overlayRef
disableAnimationbooleanポップオーバーをアニメーション化するかどうか。false
classNamesRecord<"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 プロパティ

属性説明デフォルト
childrenReactNodeトリガーが押されたときに表示されるコンテンツ。-

ポップオーバーのタイプ

ポップオーバーの配置

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/