---
title: ChromeTraceLoader
description: Read Chrome Trace Event JSON as a validated document or Arrow event table.
hide_title: true
page_style: designed
---
import {TracesDocsTabs} from '@site/src/components/docs/traces-docs-tabs';
import {DocPageHeader} from '@site/src/components/docs/doc-page-header';
import {DocOrientation, ReferenceBoundary} from '@site/src/components/docs/designed-doc';
`ChromeTraceLoader` loads Chrome Trace Event JSON. It returns an Apache Arrow event table by default,
or a validated JSON container when `chromeTrace.shape` is `json`.
## Usage
```typescript
import {load, parse} from '@loaders.gl/core';
import {ChromeTraceLoader} from '@loaders.gl/traces';
const eventTable = await load('trace.json', ChromeTraceLoader);
const traceFile = await load('trace.json', ChromeTraceLoader, {
chromeTrace: {shape: 'json'}
});
const parsed = await parse(jsonText, ChromeTraceLoader);
```
The package-root export is metadata-only. Async core APIs preload the parser from
`@loaders.gl/traces/chrome-trace-loader`. Synchronous code that needs a parser-bearing loader must
import `ChromeTraceLoaderWithParser` from that subpath.
## Return Types
| Shape | Return value |
| --- | --- |
| `json` | `ChromeTraceFileSchema`, preserving top-level and event passthrough fields. |
| `arrow` | `ChromeTraceEventArrowTable`, with file metadata attached to the Arrow schema. |
## Options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `chromeTrace.shape` | `'json' \| 'arrow'` | `'arrow'` | Whole-file result shape. |
| `chromeTrace.batchSize` | `number` | `256` | Maximum events per streamed Arrow record batch. |
| `maxLength` | `number` | `1000` | Maximum number of events structurally validated; all events are still returned. |
The legacy top-level `shape` option is also accepted and takes precedence if supplied.
Prefer `chromeTrace.shape` in new code. Arrow results retain this module's native Apache Arrow
`Table` API (`table.numRows`), not a loaders.gl `{shape, data}` wrapper.
## Batched Parsing
`parseInBatches` defaults to Arrow and yields
`ChromeTraceEventArrowRecordBatch` values with the same lossless schema used by whole-file parsing.
Explicit JSON batch output is not supported.
```typescript
import {parseInBatches} from '@loaders.gl/core';
import {ChromeTraceLoader} from '@loaders.gl/traces';
const batches = await parseInBatches(chunks, ChromeTraceLoader, {
chromeTrace: {shape: 'arrow', batchSize: 1024}
});
for await (const batch of batches) {
console.log(batch.numRows);
}
```
The tokenizer accepts string, `ArrayBuffer`, and typed-array chunks at arbitrary UTF-8 and JSON
boundaries. `displayTimeUnit` and top-level `metadata` are attached to emitted schema metadata once
they are available.
Use [Chrome trace streaming](./chrome-trace-streaming) when the destination expects live
`TraceStreamChunk` snapshots instead of Arrow record batches.