Browse docs
Read file data
Loaders turn a URL into data for your own components. Choose by format and read size: CSV and JSONL sample an initial range; JSON and Parquet read the whole file within a reported-size cap; NumPy and MCAP return metadata.
Range requests save bandwidth only when the server honors them. Use FilePreview to load and render in one component.
Overview
Shared shape
Call a loader with a URL and optional LoaderOpts; its result is specific to
the format:
Supply known size to avoid a size probe and signal to cancel fetching.
Byte and row limits apply only to the formats documented below.
useLoader
useLoader supplies data, loading and error state. Put request inputs in its
dependency array: a change clears the old result and aborts its request.
Unmounting also aborts.
HTTP helpers
These helpers are also exported from @dreamlake/viz:
| Function | Result | Request |
|---|---|---|
fetchHead(url, signal?) | { size, contentType?, lastModified? } | A one-byte Range GET to discover size. |
fetchRange(url, start, end, signal?) | Uint8Array | A byte range with an inclusive end. |
fetchText(url, signal?) | string | Complete response as text. |
fetchBytes(url, signal?) | Uint8Array | Complete response as bytes. |
fetchHead uses a one-byte GET, compatible with GET-signed URLs. Size comes
from Content-Range or Content-Length; expose these headers for cross-origin reads.
A successful full response is accepted when Range is ignored. For partial NumPy/MCAP transfers, use a server that supports Range.
loadText
Fetches the entire string. Only signal applies; check file size yourself
before loading large text.
Tabular formats
loadCsv
Samples up to 5 MiB and returns at most 1,000 string-valued rows. Detects comma, semicolon, tab or pipe delimiters, including quoted fields and a UTF-8 BOM.
Convert numeric columns yourself. totalRows is null for a partial byte
sample; otherwise it is the returned count, still limited by maxRows.
truncated also covers the row cap. bytesRead counts decoded characters,
not transferred bytes.
loadParquet
Reads and caches the whole file with hyparquet. Defaults: 5 MiB size cap and
1,000 returned rows. A reported size above the cap throws ParquetTooLargeError.
maxBytes limits reported file size; maxRows limits output, not downloads.
Top-level columns contain display values: nested objects are serialized, big
integers become strings, dates use ISO strings, and binary values show byte length.
Structured formats
loadJson
Fetches a complete document within maxBytes (default MAX_JSON_BYTES, 10 MiB).
An excessive reported size throws JsonTooLargeError with sizeBytes and capBytes.
Invalid JSON returns parseError, parsed: null and the original text.
Fetch errors throw. bytes counts characters; the size cap uses the supplied
or server-reported length.
loadJsonl
Samples up to 1 MiB and returns at most 1,000 JSON records by default. Invalid lines are skipped.
totalLines counts nonempty lines, or estimates them for a partial sample.
It may exceed records.length. truncated means the byte range was cut short;
reaching maxRows alone does not set it.
Binary formats
loadNpy
Reads dtype, shape and storage order without decoding values. A 256-byte initial request is followed by a larger header request when necessary.
Supports NPY v1–v3 scalar dtype descriptors, not structured dtypes. dataBytes
is calculated from shape and item size. maxBytes and maxRows do not apply.
loadMcap
Reads the header, footer and available summary, without decoding messages.
Expect two range requests, one more for a summary, and a size probe unless
size is supplied. Summary size determines the amount read.
Channels report topic, schema, count and rounded messageRate. Missing
summary statistics produce zero counts and unavailable timestamps; the loader
does not scan messages. Byte/row caps do not apply. Use
McapPreview to inspect message data.