DreamLake
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:

App.tsxtsx
import { FilePreview } from "@dreamlake/viz";

export function App() {
  return (
    <div style={{ height: 400 }}>
      <FilePreview
        src="/data/measurements.csv"
        metadata={{ name: "measurements.csv", ext: "csv" }}
      />
    </div>
  );
}

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:

CustomLayout.tsxtsx
import { PreviewHeader, CsvPreview } from "@dreamlake/viz";
import type { FileMetadata } from "@dreamlake/viz";

export function CustomLayout({
  file,
  src,
}: {
  file: FileMetadata;
  src: string;
}) {
  return (
    <div className="flex flex-col h-full">
      <PreviewHeader {...file} />
      <div className="flex-1 min-h-0">
        <CsvPreview src={src} metadata={file} />
      </div>
    </div>
  );
}

FilePreview dispatcher

Select a file in this demo to switch between table, JSON, text and image views:

/
trajectories.csv
Range-reading first 256 KB of CSV…
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.

sample.png
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:

tsx
import { AudioPreview } from "@dreamlake/viz";

<AudioPreview src="/data/recording.wav" />;

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.

Range-reading first 256 KB of CSV…
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.

Loading JSON…
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.

reading lines…
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.

loading text…
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.

ParquetPreview.tsxtsx
import { ParquetPreview } from "@dreamlake/viz";

<ParquetPreview src={signedUrl} metadata={file} />;

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.

NpyPreview.tsxtsx
import { NpyPreview } from "@dreamlake/viz";

<NpyPreview src={signedUrl} />;

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.

McapPreview.tsxtsx
import { McapPreview } from "@dreamlake/viz";

<McapPreview src={signedUrl} metadata={file} />;

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.

PropTypeDefaultMeaning
srcstringrequiredFile URL. The application refreshes signed URLs before expiry.
metadataFileMetadataomittedOptional file information; size lets data loaders skip a size probe. Required by FilePreview.
onSave(text: string) => Promise<void>omittedEnables editing in TextPreview. Other formats ignore it.
headerboolean | ReactNodetrueFilePreview only: use its header, hide it with false, or supply your own.

FileMetadata

FieldTypeMeaning
namestringRequired filename.
extstringOptional extension such as csv or mp4. Chooses the preview in FilePreview.
pathstringOptional full path. The header displays the parent directory, or / at the root.
sizenumberOptional byte size.
modifiedDate | stringOptional 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.

FieldTypeMeaning
sizenumberKnown byte size, avoiding a probe where the loader needs it.
signalAbortSignalCancels fetching.
maxBytesnumberByte limit for CSV, JSONL, JSON and Parquet; behavior depends on the format.
maxRowsnumberRecord limit for CSV, JSONL and Parquet.

See Read file data for defaults and return types.