UX Patterns Guide
UI + UX Disclosure And Attention Management standard

Preview panel

Provide a persistent preview panel tied to the current selection, render the content body or media with type-appropriate controls, expose blocked and unsupported states, keep source selection visible, and escalate to a full preview route when reading, annotation, or space needs exceed the panel.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • Users repeatedly inspect files, messages, PDFs, images, videos, audio, invoices, contracts, designs, or attachments from a list or grid.
  • Seeing rendered content beside the source collection prevents costly open-close navigation.
  • The preview can be safely rendered with useful fidelity and clear fallback states.
  • Users need to compare neighboring content items while retaining selection context.

Avoid when

  • Only structured metadata or activity is needed.
  • The content needs long editing, annotation, comments, shareable routes, or deep reading as the main task.
  • The viewport cannot support both source collection and readable preview without a full-view route.
  • Security, privacy, permissions, or file type support prevent trustworthy inline preview.
  • The preview appears only briefly on hover or focus and should not hold durable controls.

Problem it prevents

Content-heavy workspaces often list many documents, messages, images, videos, or attachments, and users need to inspect the selected content without losing the surrounding collection or opening a full viewer for every item.

Pattern anatomy

What a strong implementation has to make clear

User need

A source region contains selectable content objects such as files, emails, invoices, contracts, images, videos, audio, or attachments.

Pattern promise

Provide a persistent preview panel tied to the current selection, render the content body or media with type-appropriate controls, expose blocked and unsupported states, keep source selection visible, and escalate to a full preview route when reading, annotation, or space needs exceed the panel.

Required state

No selection state that asks users to choose a file, message, or media item.

Recovery path

The preview shows the previous file after selection changes.

Access contract

Name the preview region from the selected item's file name, message subject, or media title.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A document repository selects Forecast.pdf in the file list and shows page 2 in a right preview panel with page, zoom, fit width, blocked-file, download, and Open full preview controls.
  • An inbox keeps the selected email highlighted and shows the message body in a reading pane with attachment previews and a popout route.
  • A reviewer arrows through invoice files, the preview updates in place, page and zoom reset only when appropriate, and focus remains in the file list until a preview control is chosen.
  • A downloaded file marked risky shows a blocked preview state with the reason, safer choices, and an open-full route instead of rendering active remote content.
Weak implementation

Vague, hidden, hard to recover from

  • A side panel titled Preview shows only owner, modified date, and file size when reviewers need to inspect the contract body.
  • A preview pane continues rendering Budget.pdf after the selected row changed to Receipt.png.
  • The first page of a previous PDF stays visible while a new file is still loading, causing the user to approve the wrong attachment.
  • Keyboard focus jumps into the preview every time selection changes, making rapid file triage slow and disorienting.
UI guidance
  • Render a preview panel as a durable side-by-side region that shows the selected file, message, media, attachment, or document body while keeping the source list, grid, search result, inbox, or asset browser visible.
  • Give the preview panel content-fidelity controls that match the media type, such as page navigation, zoom, fit width, play or pause, transcript, alt text, unsupported-file state, safety warning, download, and open full preview.
UX guidance
  • Use a preview panel when users need to inspect content across several nearby items without repeatedly opening and closing full viewers.
  • Keep preview state, selected source item, loading, blocked content, unsupported type, permission loss, zoom, page, and full-preview escalation synchronized so users never act on the wrong file.
Implementation contract

What the implementation must handle

States

  • No selection state that asks users to choose a file, message, or media item.
  • Selected content state with source row highlighted and preview heading naming the same item.
  • Loading preview state that hides or clearly labels old content as no longer current.
  • Rendered document state with page, zoom, fit, and open-full-preview controls when the type supports them.

Interaction

  • Selecting an item updates both the source selection indicator and the preview panel title.
  • The preview panel renders the selected item's content body or media, while metadata remains supporting context.
  • Keyboard focus stays in the source list, grid, or inbox while users move selection for rapid review.
  • Preview controls update only the current selected item and announce changes such as page, zoom, fit, blocked, or open-full state.

Accessibility

  • Name the preview region from the selected item's file name, message subject, or media title.
  • Expose selected state in the source list, grid, or inbox and keep it synchronized with the preview heading.
  • Do not move focus into the preview merely because selection changed.
  • Announce meaningful preview changes such as page, zoom, fit, unsupported, blocked, or render failure through nearby status text.

Review

  • Which selected content item owns the rendered preview right now?
  • Can users see the selected source item and the preview title at the same time?
  • Does the panel render content body or media, or only metadata better suited to a details panel?
  • What happens while a new preview is loading, blocked, unsupported, deleted, or denied by permissions?
Interactive lab

Inspect the states before you copy the pattern

Preview selected content without opening it

Select Forecast.pdf, page through the preview, zoom and fit width, test blocked-file fallback, open the full preview, and compare stale-preview, metadata-only, no-fallback, unsafe-render, tiny-pane, and focus-trap failures.

Preview panel
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

No selection state that asks users to choose a file, message, or media item.

Keyboard / Access

Tab reaches the source region, preview controls, full-preview route, and collapse or resize controls in a predictable order.

Avoid Generating

Showing metadata in a preview panel when users need the document, message, or media body.
Evidence trail

Source-backed claims behind this guidance

Full agent/debug reference

Problem Context

  • A source region contains selectable content objects such as files, emails, invoices, contracts, images, videos, audio, or attachments.
  • Users must compare or triage multiple nearby items quickly while seeing each selected item's rendered body or media.
  • A partial preview is useful enough for review, but deep reading, editing, annotation, or sharing can move to a full viewer.
  • The product can detect unsupported formats, risky files, permission loss, loading, stale selection, and preview-render failures.

Selection Rules

  • Choose preview panel when users need durable rendered content beside a collection, not only metadata about the selected object.
  • Use details panel when the main content is structured fields, status, ownership, and activity rather than the document or media body.
  • Use hover card when the preview is small, transient, and appears before a navigation decision.
  • Use drawer when the surface is temporarily opened by a command and needs a close path and focus movement into it.
  • Use full-page or full-screen preview when users need long reading, annotation, page thumbnails, shareable URL state, or large media controls.
  • Use object picker with preview when the preview is part of selecting an entity for a form or workflow.
  • Do not use a preview panel when the selected content cannot be rendered safely, quickly, or accurately enough to support user decisions.
  • Do not use a preview panel as a dumping ground for filters, global navigation, settings, or unrelated actions.

Required States

  • No selection state that asks users to choose a file, message, or media item.
  • Selected content state with source row highlighted and preview heading naming the same item.
  • Loading preview state that hides or clearly labels old content as no longer current.
  • Rendered document state with page, zoom, fit, and open-full-preview controls when the type supports them.
  • Rendered image, video, audio, or message state with controls appropriate to that content type.
  • Unsupported type state with format, reason, and alternate actions such as download or open with an app.
  • Blocked or suspicious file state that explains why inline preview is disabled and offers safer choices.
  • Permission lost, deleted item, or filtered-away state that clears the rendered content and returns users to selection.
  • Narrow viewport state with collapse, resize, or full preview route.

Interaction Contract

  • Selecting an item updates both the source selection indicator and the preview panel title.
  • The preview panel renders the selected item's content body or media, while metadata remains supporting context.
  • Keyboard focus stays in the source list, grid, or inbox while users move selection for rapid review.
  • Preview controls update only the current selected item and announce changes such as page, zoom, fit, blocked, or open-full state.
  • Loading, unsupported, blocked, stale, permission, and deleted states replace the rendered content rather than letting old content appear current.
  • The panel offers a route to full preview or full object view when the content needs more space or deeper interaction.
  • Download, open with app, and external viewer actions preserve selected-item identity and communicate risk when relevant.

Implementation Checklist

  • Define the selected content ID and preview-render lifecycle before painting preview content.
  • Show the selected item in the source region and repeat its name, type, and current preview state in the panel.
  • Support media-specific controls such as page, zoom, fit, play, transcript, alt text, rotate, or full preview only when they match the selected type.
  • Handle loading, unsupported format, blocked file, suspicious source, permission loss, deleted content, filtered-away selection, and render failure.
  • Prevent stale previews by clearing or labelling old rendered content during selection changes and load failures.
  • Keep focus in the source region during rapid selection movement; move focus into preview controls only after explicit user action.
  • Provide collapse, resize, or full preview when the panel cannot keep both source context and content readable.
  • Test row selection, keyboard movement, paging, zoom, fit width, blocked preview, unsupported format, resize, and full preview route.

Common Generated-UI Mistakes

  • Showing metadata in a preview panel when users need the document, message, or media body.
  • Leaving stale rendered content visible after selection changes or preview loading fails.
  • Rendering risky downloaded or remote content without a blocked state or warning.
  • Using a preview panel for long editing, annotation, or reading workflows that need a full route.
  • Stealing focus into the preview on every source-list movement.
  • Making the preview too small to read while hiding the full-preview route.
  • Mixing preview, filters, navigation, destructive actions, and settings in one side region.

Critique Questions

  • Which selected content item owns the rendered preview right now?
  • Can users see the selected source item and the preview title at the same time?
  • Does the panel render content body or media, or only metadata better suited to a details panel?
  • What happens while a new preview is loading, blocked, unsupported, deleted, or denied by permissions?
  • Are page, zoom, fit, play, transcript, and full-preview controls present only when the content type needs them?
  • How do users reach a full viewer when the panel is too small or the task becomes deep reading or annotation?
Accessibility
  • Name the preview region from the selected item's file name, message subject, or media title.
  • Expose selected state in the source list, grid, or inbox and keep it synchronized with the preview heading.
  • Do not move focus into the preview merely because selection changed.
  • Announce meaningful preview changes such as page, zoom, fit, unsupported, blocked, or render failure through nearby status text.
  • Provide keyboard access to page, zoom, fit, play, download, open-full-preview, collapse, and resize controls.
  • Provide text alternatives, captions, transcript, or accessible fallback for image, audio, and video preview when available.
  • Do not announce old preview content as current while a new selected item is loading.
Keyboard Behavior
  • Tab reaches the source region, preview controls, full-preview route, and collapse or resize controls in a predictable order.
  • Arrow keys or source-component commands move selection and update preview content without moving focus into the panel.
  • Page controls change the previewed page and keep focus on the activated control.
  • Zoom and fit controls update preview scale and communicate the resulting state.
  • Enter or Space on Open full preview moves to the full viewer for the selected item.
  • Escape does not close a persistent preview panel unless the product has intentionally placed it in a temporary overlay mode.
  • Blocked or unsupported preview states still provide keyboard-reachable alternate actions.
Variants
  • Right preview pane
  • Reading pane
  • File preview pane
  • Document preview panel
  • Media preview panel
  • Split-view preview
  • Collapsible preview pane
  • Resizable preview pane
  • Inline full-preview route

Verification

Last verified: