vizb ui

Generate an interactive HTML chart from a vizb dataset JSON file. This is the second step in the JSON pipeline — useful when you want to generate HTML from previously merged or processed data.

Usage

vizb ui [file] [flags]

[file] is optional when --data-url is set.

Note

vizb html remains as a backward-compatible alias for vizb ui.

Input

A single JSON file containing a vizb dataset object or array. This must be JSON generated by vizb <target-file> -o file.json or vizb merge ... -o file.json.

Flags

Flag	Short	Default	Description
--output	-o	(stdout)	Output file path (HTML)
--data-url	-U	(none)	URL to fetch dataset JSON from at runtime (no input file needed)
--charts	-c	bar,line,pie	Chart types to bundle into the HTML (bar, line, scatter, pie, heatmap, radar, sankey, chord)
--3d		false	Bundle the 3D renderer when using --data-url (remote z-axis shape is unknown at build time)

Examples

Basic pipeline

# Step 1: Convert dataset to JSON
vizb bench.txt -o data.json

# Step 2: Generate HTML from JSON
vizb ui data.json -o report.html

After merging

# Merge multiple JSON files
vizb merge v1.json v2.json -o merged.json

# Render the merged result as HTML
vizb ui merged.json -o report.html

Reduce output size with --charts

By default bar, line, and pie are bundled. Pass --charts to add heatmap, radar, sankey, or chord, or to ship fewer renderers — unused chart chunks are stripped at generation time.

Selection	Approx. size
bar,line,pie (default, 2D data)	~400 kB
bar,line,pie,heatmap,radar	~445 kB
bar or line with z-axis data (embedded JSON)	~570 kB

# Bar-only report — smallest possible output (~400 KB vs ~570 KB with 3D)
vizb ui data.json -o report.html -c bar

# Bar and line only
vizb ui data.json -o report.html -c bar,line

# Pie only via remote data
vizb ui --data-url https://example.com/dataset.json -o report.html -c pie // 375K

Note

When no --charts flag is given with an input file, chunk pruning follows the union of chart types baked into each dataset’s settings. When --charts is set explicitly, embedded settings are trimmed to match and the UI only surfaces those chart tabs.

Remote data via --data-url

By default, Vizb puts the dataset inside the generated HTML. This gives you one portable file that works offline. With --data-url, Vizb generates a smaller HTML file and loads the data from an HTTP endpoint when someone opens the dashboard.

Use --data-url when the data is large, changes often, or already comes from an API. You can update the response without generating the HTML again.

vizb ui --data-url https://example.com/dataset.json -o report.html

The URL can return any of these JSON shapes:

• One complete vizb dataset object.
• An array of complete vizb dataset objects.
• A catalog containing only an id and name for each dataset. Vizb fetches the full dataset when the user selects it.

The first two shapes load all data when the page opens. A catalog keeps the initial request small and loads one dataset at a time.

Lazy catalog

A catalog response looks like this:

[
  { "id": "dataset-1", "name": "Dataset 1" },
  { "id": "dataset/2", "name": "Dataset 2" }
]

Vizb recognizes this response and requests the selected dataset from:

<data-url>/dataset/<encoded-id>

For example, selecting dataset/2 from https://api.example.com/vizb requests:

https://api.example.com/vizb/dataset/dataset%2F2

The detail response must contain one complete dataset with name, data, and settings. It may omit id; if it includes one, it must match the catalog ID. Vizb keeps loaded details in memory for the current page and lets the user retry failed requests.

You can link to a catalog entry with ?id=:

https://charts.example.com/?id=dataset%2F2

Vizb also supports the older ?d= index parameter.

Direct dataset paths

Use a data URL ending in /dataset to enable short dashboard URLs such as /<id>:

vizb ui --data-url https://api.example.com/vizb/dataset -o report.html

Opening this dashboard URL:

https://charts.example.com/dataset-1

skips the catalog request and fetches:

https://api.example.com/vizb/dataset/dataset-1

Only data URLs ending in /dataset enable this behavior. Other data URLs ignore the page path and use the normal response flow. A trailing slash, query string, or fragment on the data URL does not change the rule.

Your web host must serve the generated HTML for unmatched paths so direct links and page refreshes reach Vizb. Direct paths work on HTTP and HTTPS pages, not when opening the HTML through file://. Chart and group query parameters still work with a direct path:

https://charts.example.com/dataset-1?c=line&g=1

Response rules

Catalog IDs must be non-empty and unique. Do not mix catalog entries and complete datasets in the same array. Vizb shows a load error for invalid response shapes, duplicate IDs, malformed details, and detail IDs that do not match the request.

Vizb preserves query parameters from the data URL when it builds a detail URL and removes the fragment. The dashboard only shows chart types included when you generated the HTML, even if the remote dataset contains settings for other chart types.

Because the remote data shape is unknown at build time, the 3D engine is not bundled unless you pass --3d:

# Remote data might have a z-axis; include the 3D renderer
vizb ui --data-url https://example.com/dataset.json --3d -o report.html

With an embedded JSON file, 3D is still detected automatically from the data (no --3d needed).

Note

Without --data-url, Vizb produces a self-contained file that works offline.

Caution

Vizb embeds --data-url in the generated HTML. Do not put passwords, API keys, access tokens, or other secrets in the URL.

The data server must allow requests from the dashboard’s origin. For dashboards opened through file://, this usually requires Access-Control-Allow-Origin: *.