JSON Crack User Guide

JSON Crack turns raw data into a picture. Paste, type, or upload JSON, YAML, CSV, or XML and it instantly draws an interactive graph (or tree) you can pan, zoom, search, collapse, and export — all in your browser, with nothing sent to a server. On top of the visualizer it bundles a set of everyday data tools: format conversion, validation, jq and JSON Path queries, JSON Schema, type generation for six languages, and image export.

This guide covers everything you can do with JSON Crack across its four shipping products: the web editor at jsoncrack.com, the VS Code extension, the Chrome extension, and the jsoncrack-react npm component. Architecture, configuration internals, and self-hosting deep-dives live in the companion Admin Guide.

Note

JSON Crack is free and open source under a dual MIT/Apache-2.0 license. A separate commercial product, ToDiagram, offers higher limits, in-diagram editing, AI features, and cloud storage — but everything in this guide is available at no cost.

1. Quick Start

The fastest path to a graph takes about ten seconds and no installation.

1. Open jsoncrack.com/editor in any modern browser.
2. The editor loads with a sample document already visualized on the right.
3. Replace the text in the left-hand editor with your own data — type it, paste it, or drag a file onto the window.
4. The graph on the right redraws as you type.

Left pane (text editor)          Right pane (live graph)
┌──────────────────────┐         ┌──────────────────────────┐
│ {                    │         │   ┌─────────┐             │
│   "name": "Ada",     │  ──────▶ │   │ name: Ada│──┐         │
│   "skills": [        │         │   │ skills   │  │ ┌──────┐ │
│     "math",          │         │   └─────────┘  └▶│ math │ │
│     "logic"          │         │                  │ logic│ │
│   ]                  │         │                  └──────┘ │
│ }                    │         │                           │
└──────────────────────┘         └──────────────────────────┘

Tip

You can skip the typing entirely: append a URL to the json query parameter and JSON Crack fetches and renders it for you, e.g. https://jsoncrack.com/editor?json=https://catfact.ninja/fact.

2. The Four Products

JSON Crack ships as four separate products built from one codebase. They share the same rendering engine, so a graph looks identical everywhere.

The web editor is the flagship and carries every feature. The VS Code and Chrome extensions are focused viewers built around the same graph canvas, and jsoncrack-react is the canvas packaged for developers. Sections 5–9 cover each in turn.

Important

In every product, your data never leaves your device. Parsing, conversion, querying, and rendering all happen locally in the browser (or editor). JSON Crack has no backend that stores documents.

3. Installation & Access

3.1 Web editor — hosted

No installation. Open jsoncrack.com and click Editor, or go straight to jsoncrack.com/editor. Works in any current Chrome, Firefox, Edge, or Safari.

3.2 Web editor — self-hosted (Docker)

You can run the entire web app locally with Docker. The Docker assets live in apps/www.

docker compose (recommended)

git clone https://github.com/AykutSarac/jsoncrack.com.git
cd jsoncrack.com/apps/www

docker compose build
docker compose up

[+] Running 1/1
 ✔ Container jsoncrack  Created
Attaching to jsoncrack

Then open http://localhost:8888.

From source (Node + pnpm)

git clone https://github.com/AykutSarac/jsoncrack.com.git
cd jsoncrack.com
pnpm install
pnpm dev:www

Running on http://localhost:3000/

Note

Self-hosting requires Node.js ≥ 24 and pnpm ≥ 10. Configuration such as the node limit is covered in the Admin Guide; the most common knob is NEXT_PUBLIC_NODE_LIMIT in apps/www/.env.

3.3 VS Code extension

1. Open the Extensions view in VS Code.
2. Search for JSON Crack (publisher AykutSarac) and click Install, or install from the Marketplace page.
3. Requires VS Code 1.100.0 or newer.

3.4 Chrome extension

Install from the Chrome Web Store. It registers a content script that activates only on pages whose response is raw JSON.

3.5 React component

npm install jsoncrack-react

Requires React 18 or newer as a peer dependency. See Section 7 for usage.

4. Loading Your Data (Web Editor)

The web editor opens at /editor with a two-pane layout: a text editor on the left and the live visualization on the right, separated by a draggable divider. A toolbar sits across the top and a status bar runs along the bottom of the text editor.

There are five ways to get data into the editor.

4.1 Type or paste

Click into the left pane and start typing or paste your content. The graph updates automatically (see Live Transform). On paste, the editor auto-formats the document.

4.2 Import a file

Open the File ▸ Import dialog from the toolbar. You can either:

• Drop or click to upload a file (.json, .yaml/.yml, .csv, .xml), or
• Paste a URL to fetch a remote JSON document.

Import File
┌──────────────────────────────────────┐
│ [ URL of JSON to fetch              ] │
│ ┌──────────────────────────────────┐ │
│ │        ⬆ Drop here or click       │ │
│ │            to upload files        │ │
│ └──────────────────────────────────┘ │
│                          [ Import ]   │
└──────────────────────────────────────┘

4.3 Drag and drop anywhere

Drag a data file onto the editor window at any time. A full-screen dropzone appears confirming the drop. Accepted formats are JSON, YAML, CSV, and XML.

Warning

The full-screen dropzone enforces a maximum file size of 300 KB. Larger files are better handled by reducing the data or using a more powerful tool (see Limits & Performance).

4.4 Load from a URL parameter

Append ?json=<url> to the editor address and JSON Crack fetches and renders the document on load:

https://jsoncrack.com/editor?json=https://catfact.ninja/fact

This works on both the /editor page and the embeddable /widget page.

4.5 Session restore

When you edit data in the editor (and the content is under 80 KB and you're not inside an iframe), JSON Crack saves it to your browser's session storage, so reloading the tab keeps your work. Closing the tab clears it.

Supported input formats

5. Reading the Graph

5.1 Graph view vs. tree view

The right pane has two view modes, switched from the View menu in the toolbar. Your choice is remembered per browser tab.

In graph view, each node represents an object, array, or value. Object keys appear in one color and values in another; integers, booleans, and null each get distinct colors. URLs inside string values become clickable links, and CSS color strings (#rrggbb, rgb(), rgba()) render a small color swatch next to the value.

5.2 The graph toolbar (the floating dock)

A floating control dock sits at the bottom-center of the graph. Hover any button for a tooltip with its shortcut.

5.3 Searching nodes

Press Ctrl/⌘+F (or click the magnifier) to open the search bar. Type any key fragment; matching nodes are highlighted and the camera flies to the first match.

• Enter — jump to the next match
• Shift+Enter — jump to the previous match
• Esc — close search and clear highlights

A counter (3 / 12) shows your position; No matches appears when nothing is found.

5.4 Collapsing and expanding

Click the chevron on any object or array node to collapse that branch; click again to expand. The Collapse all / Expand all button in the dock toggles every first-level branch at once. When branches are collapsed, the button shows how many are hidden (e.g. Expand all (5 collapsed)). After a collapse, the camera keeps the clicked node pinned under your cursor so you don't lose your place.

5.5 Inspecting a node

Click any node to open the node detail modal, which shows:

• The node's content as formatted JSON, with a one-click Copy button.
• The node's JSON Path (e.g. $["customer"]["orders"][0]), also copyable.

5.6 Following edges

Click an edge to fly the camera to the node it points to — handy for tracing references in a wide graph. Edges highlight on hover.

5.7 Panning and zooming

• Drag the empty canvas to pan.
• Scroll to pan vertically; enable Zoom on Scroll in preferences to zoom with the wheel/trackpad instead.
• On touch devices, long-press to drag.

6. Preferences, Themes & Live Transform

6.1 Preferences menu

Open the gear button in the graph dock:

These settings persist in your browser between visits.

6.2 Live Transform and format conversion

The bottom status bar shows validation status (Valid / Invalid, with the error message on hover) and a format selector (JSON / YAML / XML / CSV).

• Changing the format selector converts your data in place. Switch from JSON to YAML and the editor content is rewritten as YAML; switch to CSV and it becomes CSV. This is JSON Crack's data-conversion feature — JSON↔YAML↔XML↔CSV in any direction.
• Live Transform (toggle in the status bar) controls whether the graph updates on every keystroke. When on (default), edits redraw the graph immediately. When off, edits are held until you click Click to Transform — useful for large documents where continuous re-layout is slow.

[↤ Close]  [✓ Valid]  [⟳ Live Transform]            [ JSON ▾ ]

Tip

Turn Live Transform off before pasting a large document, edit freely, then click Click to Transform once. This avoids re-rendering the graph on every keystroke.

7. Tools: Query, Validate & Generate

The Tools menu in the top toolbar opens four data utilities. Each operates on the data currently in the editor.

7.1 JSON Query (jq)

Run a jq expression against your data and replace the editor contents with the result.

1. Tools ▸ JSON Query (jq).
2. Enter a jq filter, e.g. .skills[] or .users | map(.name).
3. Click Display on Graph.

Note

JSON Crack runs a simplified, in-browser build of jq (jq-web). Most common filters work, but not every advanced jq feature is supported.

7.2 JSON Path

Evaluate a JSONPath expression. The root is always $.

1. Tools ▸ JSON Path.
2. Enter an expression, e.g. $..author or $.store.book[0].title.
3. Click Run — the matched values replace the editor contents.

7.3 JSON Schema

Apply a JSON Schema to validate your data. Validation errors appear in the bottom status bar.

1. Tools ▸ JSON Schema.
2. Paste or edit a schema (a starter Product schema is pre-filled) in the embedded editor.
3. Click Apply to enforce it, or Clear to remove it.

7.4 Generate Types / Code

Generate strongly-typed source from your JSON in six target languages.

1. Tools ▸ Generate Type.
2. Pick a language from the dropdown.
3. Copy the generated code with the Copy button.

8. Exporting

8.1 Export as image

Press Ctrl/⌘+S or click the export button in the graph dock to open Download Image.

Click Download to save the file, or Clipboard to copy the rendered image straight to your clipboard.

Warning

SVG export embeds fonts and styling but, per a known limitation, may not render perfectly when later converted to PDF because it can require external resources. For print or PDF, PNG is the most reliable choice.

8.2 Export / save the data file

Use File ▸ Export to download the current editor contents as a file named jsoncrack.<format> (e.g. jsoncrack.json, jsoncrack.yaml) matching the active format.

9. Embedding JSON Crack in Your Site

JSON Crack can be embedded in any web page three ways. Full reference lives at jsoncrack.com/docs.

9.1 Iframe widget

The simplest embed points an iframe at /widget:

<iframe
  id="json-crack-embed"
  src="https://jsoncrack.com/widget"
  width="100%"
  height="600"
  style="border: none;"
></iframe>

9.2 Load data from a URL

Pass a json query parameter pointing at a remote document and the widget fetches and renders it:

<iframe
  id="json-crack-embed"
  src="https://jsoncrack.com/widget?json=https://catfact.ninja/fact"
  width="100%"
  height="600"
  style="border: none;"
></iframe>

9.3 postMessage API (dynamic updates)

To push data into the widget at runtime, listen for its ready signal, then postMessage your payload:

const iframe = document.getElementById("json-crack-embed");

// Wait for the widget to signal it's ready
window.addEventListener("message", (event) => {
  if (event.data === "json-crack-embed") {
    // Widget is ready — send data
    iframe.contentWindow.postMessage({
      json: JSON.stringify({ hello: "world" }),
      options: {
        theme: "light",
        direction: "DOWN"
      }
    }, "*");
  }
});

Important

The iframe element must appear before the script tag. When the widget loads, it posts its own id attribute back to the parent window — wait for that message before sending data.

Message options:

10. The React Component (jsoncrack-react)

For React applications, the jsoncrack-react package embeds the same canvas natively with full control over props and callbacks.

npm install jsoncrack-react

import { JSONCrack } from "jsoncrack-react";
import "jsoncrack-react/style.css";

export function Demo() {
  return (
    <div style={{ width: "100%", height: 500 }}>
      <JSONCrack
        json={{ hello: "world", items: [1, 2, 3] }}
        theme="light"
        layoutDirection="DOWN"
        onNodeClick={(node) => console.log(node.path)}
      />
    </div>
  );
}

The json prop accepts either a string or a plain object. Common props include theme, layoutDirection, showControls, showGrid, maxRenderableNodes, and callbacks like onNodeClick, onParse, and onParseError. A complete prop and ref API reference — including imperative controls (zoomIn, centerView, collapseAll, …) — is in the Admin Guide.

Note

The package ships its own stylesheet. Importing jsoncrack-react/style.css once is required for the canvas to render correctly.

11. The VS Code Extension

Visualize the JSON file you're editing without leaving your editor. The extension works fully offline — nothing is sent to any server.

How to use

1. Install JSON Crack from the VS Code Marketplace.
2. Open a .json file.
3. Click the JSON Crack icon in the editor title bar (top-right), or run a command from the Command Palette.

The graph opens in a panel beside your code and updates live as you edit the file.

Commands

Tip

Select a fragment of a large JSON file, right-click, and choose Open with JSON Crack to graph just that slice.

Note

The extension activates automatically when your workspace contains .json files. It requires VS Code 1.100.0+.

12. The Chrome Extension

The Chrome extension (Manifest v3) injects a small Raw | Graph toggle on any page that returns raw JSON, letting you flip a plain API response into an interactive graph in place — no copy-paste, no iframe.

How to use

1. Install the extension and open a URL that responds with raw JSON (e.g. a REST API endpoint in your browser).
2. A floating Raw | Graph segmented control appears.
3. Click Graph to render the visualization; click Raw (or press Esc) to return to the browser's default view.
4. Click any node to open a content/JSON-path modal with copy buttons.

Privacy

The extension is built to minimize data handling: no sign-in, no analytics or telemetry SDK, and no persistent storage of page JSON. It reads page text only to detect JSON, renders locally in the tab, reads your system light/dark preference for theming, and writes to the clipboard only when you click a copy button.

Note

Because the page content is captured once when the toggle is injected, single-page-app JSON viewers that swap the payload without a full reload won't refresh the graph automatically — reload the page to re-capture.

13. Keyboard Shortcuts

These work in the web editor's graph view (use ⌘ on macOS, Ctrl elsewhere).

14. Limits & Performance

JSON Crack imposes two independent limits to keep the browser responsive:

When a document exceeds the node limit, JSON Crack shows an overlay explaining the graph is too large to render rather than freezing the tab.

Tip

If you self-host, raising NEXT_PUBLIC_NODE_LIMIT lets you visualize larger documents at the cost of render performance. The bundled dev configuration already uses a higher limit (2,000) than production (1,200).

Caution

Actual capacity varies with data complexity and your hardware. Very deep or very wide structures hit the limit sooner than flat ones of the same byte size.

15. Troubleshooting

Error: This graph has N nodes and exceeds the limit

Cause: Your document produces more nodes than the configured maximum (~1,200 on the hosted site). Solution: Reduce the data, collapse/visualize a sub-section, or self-host with a higher NEXT_PUBLIC_NODE_LIMIT. Prevention: For routinely large files, self-host or use a tool designed for big datasets.

Error: Failed to fetch JSON!

Cause: The URL you supplied (in Import or via ?json=) didn't return valid JSON, or the request was blocked by the remote server's CORS policy. Solution: Confirm the URL returns JSON directly in a browser and that the server allows cross-origin requests. Prevention: Host the data on a CORS-enabled endpoint, or download and import the file.

Error: Invalid (red, in the bottom status bar)

Cause: The current editor content is not valid in the selected format. Hover the Invalid badge for the exact parser message. Solution: Fix the syntax at the indicated location, or switch the format selector to match your data's actual format. Prevention: Paste into the editor (which auto-formats) rather than typing structure by hand.

Large file is truncated or won't load

Cause: Files over ~300 KB are rejected by the dropzone; very large pasted content may exceed the node limit. Solution: Trim the document, or paste a representative subset. Prevention: See Limits & Performance.

The graph doesn't update while I type

Cause: Live Transform is turned off in the bottom status bar. Solution: Click Live Transform to re-enable it, or click Click to Transform to apply the current edit once. Prevention: Leave Live Transform on for small documents.

Numbers lose precision (very large integers)

Cause: Values larger than a 64-bit integer can lose accuracy during JavaScript parsing. Solution: Treat such fields as strings in your source data if exact precision matters. Prevention: Quote oversized numeric IDs in the source JSON.

Editor shows "upgrade to premium" or asks me to choose an editor

Cause: On first visit per day the hosted editor shows a one-time Choose your editor dialog promoting ToDiagram alongside the free open-source editor. Solution: Click Stay on JSON Crack to continue free; it won't reappear that day. Prevention: Self-host and set NEXT_PUBLIC_DISABLE_EXTERNAL_MODE=true to suppress these prompts.

Chrome extension graph is stale after the API data changed

Cause: The extension captures page JSON once when injected and does not track in-place SPA updates. Solution: Reload the page to re-capture the current response.

16. Frequently Asked Questions

Q: What is JSON Crack and what does it do? It's an online viewer that visualizes and analyzes JSON, YAML, CSV, and XML, turning structured data into interactive graphs and tree views for developers, analysts, and anyone working with data.

Q: How is it different from a traditional JSON viewer? Traditional viewers and formatters keep you in raw text. JSON Crack adds a visual representation — graph and tree views — that makes complex structures far easier to understand and navigate.

Q: Is JSON Crack free? Yes — it's a free-forever, open-source tool. Advanced/commercial features are available separately via ToDiagram.

Q: Is my data secure? Yes. Data you paste or import is processed entirely in your browser to build the visualization; it never goes to JSON Crack's servers.

Q: Which data formats are supported? JSON, YAML, XML, and CSV — for both input and conversion.

Q: Can I convert between formats? Yes. Use the format selector in the bottom bar to convert JSON ↔ YAML ↔ XML ↔ CSV in place.

Q: What size of data can I visualize? Roughly 300 KB, varying with data complexity and your hardware. The graph also has a node-count limit (~1,200 on the hosted site).

Q: Can I export the graphs? Yes — as PNG, JPEG, or SVG, with a configurable background color, or straight to your clipboard.

Q: How do I use the VS Code extension? Install it from the Marketplace, open a .json file, and click the JSON Crack icon in the editor title bar.

Q: I previously subscribed to the premium plan — where did it go? Premium features moved to ToDiagram.com; the same credentials manage that subscription.

Q: Can I embed JSON Crack in my own site? Yes — via an iframe widget, a URL parameter, the postMessage API, or the jsoncrack-react component. See Section 9.

17. Quick Reference

Editor menus

Supported formats

JSON · YAML · XML · CSV (input, conversion, and file import)

Code generation targets

TypeScript · TypeScript (combined) · Go · JSON Schema · Kotlin · Rust

Image export formats

PNG · JPEG · SVG

Useful links