Image Preview Guide

This guide covers how to display image files inline using image-preview code blocks.

Overview

The image-preview block renders local image files inline in chat messages — showing the image in a fixed-height container with an expand button for fullscreen viewing.

Format	Best For	Rendering
image-preview block	Screenshots, captures, visual diffs	Inline fit-to-container + fullscreen viewer
pdf-preview block	PDF reports and documents	First page inline + full navigation
html-preview block	Rich HTML content	Sandboxed iframe rendering

Key principle: Images are already files on disk. Reference them directly with an absolute path in src.

When to Use

Use image-preview when:

• You have a local screenshot/capture file and want inline visual context
• You want before/after visual comparisons in one response
• A tool result generated or downloaded image files
• The user asks to view an image directly in chat

Do NOT use image-preview when:

• The content is a PDF (pdf-preview)
• The content is rich HTML (html-preview)
• The content is structured table data (datatable/spreadsheet)
• The file format is unsupported in Chromium (often HEIC/HEIF/TIFF)

Basic Usage

Single Item

```image-preview
{
  "src": "/absolute/path/to/screenshot.png",
  "title": "Settings screen"
}
```

Multiple Items (Tabs)

Use items to show related images with tab navigation.

```image-preview
{
  "title": "Before / After",
  "items": [
    { "src": "/path/to/before.png", "label": "Before" },
    { "src": "/path/to/after.png", "label": "After" }
  ]
}
```

Content loads lazily on tab switch and is cached once loaded.

Config Fields

Field	Required	Type	Description
src	Yes*	string	Absolute path to image file (single item mode)
title	No	string	Header title (defaults to “Image Preview”)
items	Yes*	array	Array of image items with src and optional label
items[].src	Yes	string	Absolute path to image file
items[].label	No	string	Tab label

*Either src (single) or items (multiple) is required. If both are present, items takes precedence.

Supported Formats

In-app preview supports Chromium-decodable formats:

• PNG, JPG, JPEG, GIF, WebP, SVG, BMP, ICO, AVIF

Formats like HEIC/HEIF/TIFF may not render in-app. For those files, use external open.

Rendering Behavior

Inline Preview

• Fixed 400px preview area
• Image is rendered with object-contain (no cropping)
• Expand button opens fullscreen overlay
• Multi-item blocks show item navigator in the header

Fullscreen Overlay

• Larger fit-to-container image view
• Item navigation (arrows/dropdown) for multi-item sets
• Copy path action in header
• File path badge supports external open/reveal actions

Troubleshooting

“Loading…” shown indefinitely

• Verify src is an absolute path
• Confirm the file exists and is readable
• Check that file extension is one of the supported formats

“Load Failed” error

• File path may be invalid or access may be denied
• Image may be corrupted
• Format may not be decodable by Chromium

HEIC/TIFF doesn’t render

• Expected for many environments
• Open externally using the file path badge actions