Skip to content

feat: virtualized rendering for large JSON (#32) #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
brycewc wants to merge 8 commits into
base: main
Choose a base branch
from
Open

feat: virtualized rendering for large JSON (#32) #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
242b5d4
feat: virtualized rendering for large JSON (#32)
brycewc Jul 15, 2026
e22a710
feat: virtualized rendering for large JSON (#32)
brycewc Jul 15, 2026
32466c6
Merge branch 'virtualization-support' of https://github.com/brycewc/r…
brycewc Jul 16, 2026
1f658c7
Fixed corrupted package.json
brycewc Jul 16, 2026
f926988
Added react-dom to peer dependencies
brycewc Jul 16, 2026
f559cd8
Added react-dom to peer dependencies
brycewc Jul 16, 2026
fdc5df2
Merge branch 'virtualization-support' of https://github.com/brycewc/r…
brycewc Jul 16, 2026
d8a9335
new scrollRef to allow consumes to own the scroll instead of the pack…
brycewc Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,53 @@ import 'react18-json-view/src/style.css'
| `CopyComponent` \/ `DoneComponent` \/ `CancelComponent` | `React.FC` \/ `React.Component` `<{ onClick: (event: React.MouseEvent) => void; className: string ; style: React.CSSProperties}>` | - | Customize copy icon. |
| `CopiedComponent` | `React.FC` \/ `React.Component` `<{ className: string; style: React.CSSProperties }>` | - | Customize copied icon. |
| `CustomOperation` | `React.FC` \/ `React.Component` `<{ node: any }>` | - | Custom Operation |
| `virtual` | `boolean` \| `'auto'` | `'auto'` | Windowed rendering. `'auto'` virtualizes only when the visible-row count exceeds `rowVirtualThreshold` or a `height`/`maxHeight` is set. `true` always windows; `false` forces the legacy inline render. |
| `rowVirtualThreshold` | `integer` | `100` | Under `virtual='auto'`, the visible-row count above which windowing turns on. |
| `height` | `number` \| `string` | - | Fixed height of the scroll viewport (enables windowing). |
| `maxHeight` | `number` \| `string` | `'70vh'` when windowed and no `height` | Grow-to-content up to this height, then scroll. |
| `estimatedRowHeight` | `integer` | `20` | Estimated row height (px) used before a row is measured. |
| `overscan` | `integer` | `8` | Number of rows rendered beyond the viewport on each side. |

### Virtualization

Since **v0.3**, the tree is rendered from a flattened list of visible rows, and large documents are
windowed with [`@tanstack/react-virtual`](https://tanstack.com/virtual) so only the rows in view are
mounted. This keeps rendering and interaction fast on documents with tens of thousands of nodes.

By default (`virtual='auto'`) small/medium documents render inline exactly as before; windowing turns on
automatically once the visible-row count exceeds `rowVirtualThreshold`, or as soon as you set a `height`
or `maxHeight`. When windowed, the component becomes a bounded, scrollable box.

```tsx
// Explicit bounded viewport — always windowed
<JsonView src={hugeData} height={400} />

// Grow up to 60vh, then scroll
<JsonView src={hugeData} maxHeight="60vh" />

// Opt out of windowing entirely (legacy inline rendering)
<JsonView src={data} virtual={false} />
```

Notes:

- Windowing is **client-only**. Under SSR, small documents render inline (safe to hydrate); force
`virtual={false}` if you server-render very large documents.
- A node passed to `customizeNode` that returns a React element/component renders as a single measured
row; its own subtree is not internally windowed.

#### Migration from v0.2

`v0.3` is a breaking (major) change of the rendering internals:

- **Bounded height by default for large data.** Once a document is large enough to virtualize, the
component renders inside a scroll container instead of growing to full content height. Pass
`virtual={false}` to restore the old unbounded layout.
- **`onCollapse` semantics fixed.** It no longer fires on mount, and `isCollapsing` is now `true` when a
node is being collapsed (previously the flag was inverted). It fires only on user toggles.
- The recursive DOM (`.jv-indent` blocks, one `.json-view--pair` per key) is replaced by a flat list of
`.jv-row` elements indented via `padding-left`. `onEdit`/`onDelete`/`onAdd`/`onChange` payloads
(including `depth`, `parentPath`, `indexOrName`, `parentType`) are unchanged.

### Collapsed function

Expand Down
21 changes: 16 additions & 5 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
{
"name": "react18-json-view",
"version": "0.2.10",
"version": "0.3.0",
"type": "module",
"description": "JSON viewer for react18",
"main": "dist/cjs/index.cjs",
"types": "dist/index",
"module": "dist/es/index.mjs",
"brower": "dist/es/index.mjs",
"browser": "dist/es/index.mjs",
"scripts": {
"dev": "rollup -cw",
"dev:website": "turbo run dev --filter=website...",
"build": "rollup -c",
"test": "vitest run",
"test:watch": "vitest",
"storybook": "storybook dev -p 6006",
"build-storybook": "storybook build",
"prepare": "husky install",
Expand All @@ -35,11 +37,16 @@
"@storybook/react": "^7.3.2",
"@storybook/react-vite": "^7.3.2",
"@svgr/rollup": "^8.1.0",
"@testing-library/jest-dom": "^6.1.5",
"@testing-library/react": "^14.3.1",
"@testing-library/user-event": "^14.5.2",
"@types/node": "^18.11.18",
"@types/react": "^18.0.26",
"@types/react-dom": "^18.0.8",
"@vitejs/plugin-react": "^4.2.1",
"autoprefixer": "^10.4.14",
"husky": "^8.0.3",
"jsdom": "^23.0.1",
"lint-staged": "^13.1.0",
"postcss": "^8.4.23",
"postcss-loader": "^7.2.4",
Expand All @@ -55,10 +62,13 @@
"tslib": "^2.7.0",
"turbo": "^1.10.13",
"typescript": "^5.0.4",
"vite-plugin-svgr": "^3.2.0"
"vite": "4.4.9",
"vite-plugin-svgr": "^3.2.0",
"vitest": "^0.34.6"
},
"peerDependencies": {
"react": ">=16.8.0"
"react": ">=16.8.0",
"react-dom": ">=16.8.0"
},
"lint-staged": {
"**/*": "prettier --write --ignore-unknown"
Expand Down Expand Up @@ -98,6 +108,7 @@
"*.css"
],
"dependencies": {
"@tanstack/react-virtual": "3.14.6",
"copy-to-clipboard": "^3.3.3"
}
}
}
Loading