README.md

virtual-react-json-diff

👉 Try it now

A high-performance React JSON diff viewer for large, real-world JSON data.

Built to handle tens of thousands of lines without freezing the UI, it uses virtualized rendering to stay fast and responsive even in production-scale scenarios.

Powered by json-diff-kit, it supports virtual scrolling, advanced comparison options, search, dual minimaps, and customizable theming.

Why virtual-react-json-diff exists

Most JSON diff viewers work well for small examples, but start breaking down in real-world scenarios:

• Large JSON files cause the UI to freeze or crash
• Rendering thousands of DOM nodes makes scrolling unusable
• Array changes are hard to reason about without object-level comparison
• It’s difficult to understand the impact of changes beyond raw diffs

virtual-react-json-diff was built to solve these problems.

It is designed for internal dashboards and developer tools that need to compare large, deeply nested JSON objects efficiently and interactively.

Key Features

virtual-react-json-diff is designed for scenarios where traditional diff viewers become unusable due to size or complexity.

Built for Large JSONs

• Virtualized rendering powered by react-window
• Smooth scrolling and interaction even with very large diffs

Navigate Complex Changes

• Dual minimap with visual change indicators
• Jump directly to changes using search highlighting
• Optional single minimap for compact layouts

Understand Change Impact

• Line count statistics for added, removed, and modified lines
• Object-level statistics when using compare-key array diffs
• Quickly assess how big or risky a change really is

Advanced Comparison Control

• Ignore specific keys or paths anywhere in the JSON tree
• Multiple comparison strategies (strict, loose, type-aware)
• Fine-grained control over how values are considered equal

Customizable & Extensible

• Custom class names for theming
• Inline diff customization
• Access raw diff data for advanced use cases

Demo

👉 Try it now - Interactive demo with live examples

Installation

npm install virtual-react-json-diff
# or
yarn add virtual-react-json-diff
# or
pnpm add virtual-react-json-diff

Usage

import { VirtualDiffViewer } from "virtual-react-json-diff";

const oldData = { name: "Alice", age: 25 };
const newData = { name: "Alice", age: 26, city: "NYC" };

export default function App() {
  return (
    <VirtualDiffViewer
      oldValue={oldData}
      newValue={newData}
      height={600}
      showLineCount={true}
      showObjectCountStats={false}
    />
  );
}

Understanding Diff Configuration

The viewer exposes two different configuration layers, each serving a distinct purpose.

Quick Mental Model

• differOptions → Controls how the diff is generated
• comparisonOptions → Controls what is compared and how values are matched

differOptions — How the diff works

These options are passed directly to the underlying diff engine.

Use them to:

• Choose how arrays are compared (compare-key, positional, etc.)
• Define comparison keys for object arrays
• Control depth, circular detection, and modification behavior

differOptions={{
  arrayDiffMethod: "compare-key",
  compareKey: "id",
  maxDepth: 999
}}

comparisonOptions — What is considered equal or ignored

These options affect comparison behavior without changing the diff structure.

Use them to:

• Ignore volatile fields (timestamps, metadata)
• Exclude specific paths
• Compare values across types

comparisonOptions={{
  ignoreKeys: ["updatedAt", "__typename"],
  ignorePaths: ["meta.timestamp"],
  compareStrategy: "type-aware"
}}

Using Both Together

<VirtualDiffViewer
  oldValue={oldData}
  newValue={newData}
  differOptions={{
    arrayDiffMethod: "compare-key",
    compareKey: "id"
  }}
  comparisonOptions={{
    ignoreKeys: ["updatedAt"],
    compareStrategy: "type-aware"
  }}
/>

This separation keeps the diff engine flexible while allowing precise control over comparison behavior.

Props

Required

Prop	Type	Description
oldValue	object	Original JSON object (left side).
newValue	object	Updated JSON object (right side).

---

Layout & Display

Prop	Type	Default	Description
height	number	—	Height of the diff viewer in pixels.
leftTitle	string	—	Optional title shown above the left panel.
rightTitle	string	—	Optional title shown above the right panel.
className	string	—	Custom CSS class applied to the root container.

---

Search & Navigation

Prop	Type	Default	Description
hideSearch	boolean	false	Hides the search bar when set to true.
searchTerm	string	""	Initial search term to highlight in the diff.
onSearchMatch	(index: number) => void	—	Callback fired when a search match is found.
showSingleMinimap	boolean	false	Show a single minimap instead of dual minimaps.
miniMapWidth	number	40	Width of each minimap in pixels.

---

Statistics & Insights

Prop	Type	Default	Description
showLineCount	boolean	false	Display added, removed, and modified line counts.
showObjectCountStats	boolean	false	Display object-level stats (requires compare-key array diffing).

Note: showObjectCountStats only works when differOptions.arrayDiffMethod = "compare-key" and compareKey is provided.

---

Diff Configuration

Prop	Type	Default	Description
differOptions	DifferOptions	Engine defaults	Controls how the diff is generated (arrays, depth, keys).
comparisonOptions	DiffComparisonOptions	—	Controls what is compared and how values match.
inlineDiffOptions	InlineDiffOptions	{ mode: "char" }	Fine-tune inline diff rendering behavior.

---

Advanced & Utility

Prop	Type	Default	Description
getDiffData	(diffData: [DiffResult[], DiffResult[]]) => void	—	Access raw diff results for custom processing or analytics.

Styling

The component exposes a root container with class diff-viewer-container. You can pass your own class name via the className prop to apply custom themes.

🙌 Acknowledgements

Built on top of the awesome json-diff-kit.

License

MIT © Utku Akyüz

Contributing

Pull requests, suggestions, and issues are welcome!