Browse docs
Preview a file
Inspect a recording, table or artifact from its URL with FilePreview. The
metadata.ext field selects the viewer; data previews handle loading and errors.
Start with the dispatcher demo below to try the supported formats.
For a known format, use its component directly, such as CsvPreview. For custom
parsing or layout, combine loaders with
views.
Usage
Pass the URL and extension explicitly:
Supply a browser-accessible URL. For a local file, use
URL.createObjectURL(file) and revoke the URL after the preview releases it.
Refresh signed URLs in the application before they expire.
Set header={false} to hide the header or pass a React element to replace it.
A per-format preview also works inside your own layout:
FilePreview dispatcher
Select a file in this demo to switch between table, JSON, text and image views:
Code FilePreviewSpec.tsx
Built-in routing covers images, video, audio, text, CSV, Parquet, JSON, JSONL,
NumPy and MCAP. Unknown extensions show an unsupported-format state. Route any
additional formats in your application before falling back to FilePreview.
extToKind and the exported extension sets expose the built-in routing.
Media
ImagePreview
Shows the image and file metadata, adding natural resolution after loading.
Code ImagePreviewSpec.tsx
VideoPreview
Shows video controls, duration and resolution. The browser must support the codec; server Range support enables partial reads when seeking.
Code VideoPreviewSpec.tsx
When the browser can't decode it
Try the failure below to inspect the network, decode or unsupported-source message. Missing video dimensions also produce an error. A stalled player stays mounted so it can recover when data arrives.
Code VideoErrorSpec.tsx
Use VideoView directly to set stallMs or handle VideoErrorInfo through
onError.
AudioPreview
Use the native audio player with a URL and optional file metadata:
Data formats
CsvPreview
Preview the first 5 MiB and at most 1,000 CSV rows. The summary reports the detected delimiter and whether the preview is truncated.
Code CsvPreviewSpec.tsx
JsonPreview
Inspect a JSON value in tree or raw form. Invalid JSON keeps the raw text and shows the parse error. The reported file-size limit is 10 MiB.
Code JsonPreviewSpec.tsx
JsonlPreview
Inspect JSONL records from an initial byte sample. Invalid lines are skipped; the total line count is estimated when the sample is truncated.
Code JsonlPreviewSpec.tsx
TextPreview
Loads the full text. Supplying onSave enables editing; resolve its promise
after persisting the change, or reject to show an error. Try saving more than
4 KiB in this demo to see the error state.
Code TextPreviewSpec.tsx
Check text-file size before opening it. To change data-preview limits, call the loader and render a view.
Binary formats
ParquetPreview
Loads the full file and displays up to 1,000 rows, with a 5 MiB reported-size cap.
For other limits, combine loadParquet with TableView.
NpyPreview
Inspect dtype, shape, element count and storage order without decoding values. The loader requests a 256-byte header range, then a longer header if necessary.
McapPreview
Inspect an MCAP recording as one episode. Recognized image, point-cloud, transform and numeric topics generate views sharing a time cursor. Check the reader support and layout rules for your topics.
Copy .dreamrc copies the generated layout as YAML for editing and saving.
If interactive opening fails, the preview shows metadata, channels and the reason. If metadata loading itself fails, it shows an error instead.
Props reference
PreviewProps
Per-format previews share PreviewProps. The dispatcher additionally requires
metadata and accepts header.
| Prop | Type | Default | Meaning |
|---|---|---|---|
src | string | required | File URL. The application refreshes signed URLs before expiry. |
metadata | FileMetadata | omitted | Optional file information; size lets data loaders skip a size probe. Required by FilePreview. |
onSave | (text: string) => Promise<void> | omitted | Enables editing in TextPreview. Other formats ignore it. |
header | boolean | ReactNode | true | FilePreview only: use its header, hide it with false, or supply your own. |
FileMetadata
| Field | Type | Meaning |
|---|---|---|
name | string | Required filename. |
ext | string | Optional extension such as csv or mp4. Chooses the preview in FilePreview. |
path | string | Optional full path. The header displays the parent directory, or / at the root. |
size | number | Optional byte size. |
modified | Date | string | Optional modification time. Dates are formatted; strings display as supplied. |
LoaderOpts
Previews supply metadata.size and a cancellation signal. Configure byte or row
limits by calling the loader yourself.
| Field | Type | Meaning |
|---|---|---|
size | number | Known byte size, avoiding a probe where the loader needs it. |
signal | AbortSignal | Cancels fetching. |
maxBytes | number | Byte limit for CSV, JSONL, JSON and Parquet; behavior depends on the format. |
maxRows | number | Record limit for CSV, JSONL and Parquet. |
See Read file data for defaults and return types.