preview-panel

About

• Pan & zoom via drag, scroll wheel, and pinch-to-zoom gestures, behind a lock so the page scrolls past the panel until the user unlocks it
• An actions slot for your own buttons beside the zoom controls
• Built-in zoom controls with percentage badge
• Zero re-renders during continuous interactions (ref-based transforms)
• unsafeHtml prop for rendering raw HTML/SVG content directly (caller-sanitized; XSS sink)
• Fullscreen dialog variant with PreviewPanelDialog
• Synced state between inline and dialog panels via syncPanels
• RAF-batched state emission for maximum performance
• Built with gentleduck/ui components: Button, Badge, ButtonGroup, Separator, Tooltip, Dialog

Philosophy

Preview panels bridge the gap between list views and detail views. Instead of navigating away to see content, users get an inline preview that respects their current context. We ship this as a compound component because the trigger, content, and dialog modes each need independent control while sharing state.

How It's Built

Installation

npx @gentleduck/cli add preview-panel

npx @gentleduck/cli add preview-panel

Usage

import { PreviewPanel } from '@/components/ui/preview-panel'

<PreviewPanel maxHeight="400px">
  <YourContent />
</PreviewPanel>

Locking

Drag, wheel and pinch start locked, so scrolling a page past the panel scrolls the page. The lock button in the controls turns them on, and the zoom buttons work either way. Start unlocked where the panel is the page's main content:

<PreviewPanel defaultLocked={false} maxHeight="400px">
  <YourContent />
</PreviewPanel>

With actions

actions renders in the toolbar before the zoom controls, and still renders with showControls={false}.

<PreviewPanel actions={<Button size="icon-sm" icon={<Copy />} aria-label="Copy" />}>
  <YourContent />
</PreviewPanel>

With HTML content

<PreviewPanel unsafeHtml="<svg>...</svg>" maxHeight="400px" />

With dialog and sync

import { PreviewPanelDialog } from '@/components/ui/preview-panel'

<PreviewPanelDialog syncPanels maxHeight="400px">
  <YourContent />
</PreviewPanelDialog>

Examples

HTML / SVG content

Render raw HTML or SVG strings directly using the unsafeHtml prop. The value is rendered verbatim via dangerouslySetInnerHTML and is not sanitized, so only pass HTML you fully trust.

Dialog with synced zoom

Open the content in a fullscreen dialog. Zoom and position sync between both panels, and the fullscreen panel starts unlocked.

Image viewer

Use as a zoomable image viewer.

RTL Support

Set the direction once with DirectionProvider (or <html dir="rtl">) and the panel follows: the zoom controls move to the top-left corner and lay out RTL. Use zoomInText, zoomOutText, resetText, lockText, and unlockText to translate the control labels.

Motion

Use MotionPreviewPanel for a smooth entrance animation powered by motion. The panel uses a scaleIn entrance (fade, scale, and blur) with a bouncy spring transition on mount, and its internal controls (buttons, separators, badges, tooltips) use the full motion stack.

API Reference

PreviewPanel

The core pan-zoom container.

MotionPreviewPanel

scaleIn entrance (fade, scale, and blur) with springBouncy transition on mount. Zoom controls use MotionButton, MotionBadge, MotionSeparator, and MotionTooltip internally. Requires the motion package.

PreviewPanelDialog

Combines an inline PreviewPanel with a fullscreen Dialog. The expand button sits in the inline panel's toolbar, before the zoom controls. The inline panel starts locked and the fullscreen one unlocked.

PreviewPanelState

The state object used for syncing between panels.

type PreviewPanelState = {
  zoom: number
  x: number
  y: number
}