Floating Viewer

Use Floating Viewer to keep reference media visible while someone works elsewhere on the page. It can detach automatically when its inline position leaves the viewport or through an explicit control.

Preview

Reduce motion:Off

Inspect

Component walkthrough

Installation

Motion

npx shadcn@latest add @sona-ui/floating-viewer

Usage


"use client";
 
import FloatingViewer from "@/components/ui/floating-viewer/floating-viewer";
 
export default function FloatingViewerDemo() {
  return (
    <div className="grid w-full max-w-4xl gap-8 lg:grid-cols-[1.2fr_0.8fr]">
      <div className="space-y-3">
        <p className="font-medium text-sm">Component walkthrough</p>
        <FloatingViewer>
          {/* biome-ignore lint/a11y/useMediaCaption: this demo video has no audio track */}
          <video
            aria-label="Sona UI animated dialog walkthrough"
            className="size-full object-cover"
            controls
            playsInline
            poster="/videos/posters/animated-dialog-poster.webp"
            preload="metadata"
            src="/videos/animated-dialog.mp4"
          />
        </FloatingViewer>
      </div>
 
      <form
        className="space-y-4 rounded-2xl bg-muted/45 p-5"
        onSubmit={(event) => event.preventDefault()}
      >
        <div>
          <h3 className="font-medium text-sm">Try it alongside the tutorial</h3>
          <p className="mt-1 text-muted-foreground text-xs leading-5">
            Float the video, then complete these fields without losing your
            place.
          </p>
        </div>
        <label className="block space-y-1.5 text-xs">
          <span className="font-medium">Project name</span>
          <input
            className="h-10 w-full rounded-xl bg-background px-3 outline-none ring-1 ring-border focus:ring-2 focus:ring-foreground/25"
            placeholder="Motion study"
          />
        </label>
        <label className="block space-y-1.5 text-xs">
          <span className="font-medium">Notes</span>
          <textarea
            className="min-h-24 w-full resize-none rounded-xl bg-background p-3 outline-none ring-1 ring-border focus:ring-2 focus:ring-foreground/25"
            placeholder="Capture what you notice..."
          />
        </label>
      </form>
    </div>
  );
}

Props

Property	Type	Default	Description
`children`	`ReactNode`	`required`	Media or reference content that remains mounted while the viewer moves.
`ariaLabel`	`string`	`"Floating media viewer"`	Accessible name announced for the floating viewer.
`aspectRatio`	`string`	`"16 / 9"`	CSS aspect-ratio value used by both viewer states.
`floatingWidth`	`number`	`320`	Width of the floating surface in pixels.
`viewportPadding`	`number`	`16`	Gap between the floating surface and viewport edges in pixels.
`defaultCorner`	`FloatingViewerCorner`	`"bottom-right"`	Corner used when the viewer first detaches.
`floatOnExit`	`boolean`	`true`	Automatically detach when the inline viewer leaves the viewport.
`showFloatControl`	`boolean`	`true`	Shows the built-in Float button while the viewer is inline.
`onFloatingChange`	`(floating: boolean) => void`	`undefined`	Called whenever the viewer enters or leaves its floating state.
`surfaceClassName`	`string`	`undefined`	Additional CSS classes for the media surface.

Accessibility

The floating surface is announced as a labeled region and every action is available without dragging. Restore scrolls the inline position into view, while Close suppresses automatic floating until the inline viewer becomes visible again.

Motion

The viewer uses a critically damped spring to preserve spatial continuity while snapping between corners. Reduced-motion preferences replace spatial movement with immediate state changes.

Styling

Use the component for one persistent media surface and let the consumer own the media controls, captions, and content. Avoid placing important page controls beneath the viewport corners where the floating surface can rest.

Was this component useful?

Your feedback helps us improve the documentation.