Popover and dialog

Keep the surface in the same render tree. Web Components use a root-owned <template slot="content">; Vue uses FloatingContent with the same default; direct Web uses createFloatingTopLayer({onOpenChange}) and binds the existing element.

These compositions opt into the browser’s standard Popover API, so stacking and light-dismiss behavior come from the platform rather than a framework-specific portal implementation.

Native Popover owns top-layer stacking and light dismissal. Do not portal the same surface as well.

Use a real <dialog> when the browser should own modal focus, inertness, Escape handling, and the top layer. In Web Components this is <dialog slot="floating">; in Vue it is <FloatingContent as="dialog">.

Both forms use the browser’s standard <dialog> element, including its modal focus and inertness behavior.

When a native dialog is open, Floating UI Plus also applies a ref-counted document scroll lock. It uses the platform’s overflow: hidden behavior and does not install a touch-event interception layer by default. Applications targeting legacy iOS Safari or a constrained WebView can add an app-specific touch guard when needed.

Native dialogs also receive data-fup-safe-area and the CSS variables --fup-safe-area-inset-top, --fup-safe-area-inset-right, --fup-safe-area-inset-bottom, and --fup-safe-area-inset-left. The package does not force padding onto every dialog because centered dialogs, edge sheets, and custom layouts need different spacing. Apply the variables where content needs protection from a notch or home indicator:

.sheet-panel[data-fup-safe-area] {
  padding-block-start: max(1rem, var(--fup-safe-area-inset-top));
  padding-block-end: max(1rem, var(--fup-safe-area-inset-bottom));
  padding-inline: max(1rem, var(--fup-safe-area-inset-left))
    max(1rem, var(--fup-safe-area-inset-right));
}

Use a portal only when the surface must move to a body-level target, such as escaping a clipping ancestor. Add an overlay or focus manager for a custom non-native modal composition.

See the modal demo for a native dialog and nested floating surface. See Entry and exit animation to let CSS animate native Popover and dialog surfaces in both directions without JavaScript timers.

Popover and dialog

Non-modal anchored surfaces

Modal surfaces