Data Display

JsonDiffViewer

Structural comparison of two JSON values: added, removed and changed entries at any depth, with unchanged entries collapsed and long levels paged.

import { JsonDiffViewer } from '@lostgradient/cinder';
diffjsoncompare
01

Overview

Reference usage

Structural comparison of two JSON values: added, removed and changed entries at any depth, with unchanged entries collapsed and long levels paged.

Usage

svelte
<script lang="ts">
  import { JsonDiffViewer } from '@lostgradient/cinder';
</script>

<JsonDiffViewer
  before={{ status: 'queued', retries: 3, tags: ['etl'] }}
  after={{ status: 'running', retries: 3, tags: ['etl', 'nightly'] }}
/>

A panel imports the same component from @lostgradient/cinder/panel, beside mountPanel.

How values compare

  • Objects compare by key and arrays by index, to any depth up to maxDepth. Inserting at the front of an array shows as every later index changing.
  • A value that changes type, such as a number that becomes a string or an object that becomes an array, shows as one removed entry and one added entry, never as one change.
  • A changed object or array nests its own differences under its key. An added or removed one shows as a one-line size, such as {3 keys} or [2 items].
  • Each row leads with a symbol and a name besides its tint: + added, - removed, ~ changed and = unchanged. A changed entry reads before → after on one line.
  • Unchanged entries start collapsed behind a control that names how many it holds.
  • A level renders its first 200 entries; a "Show 200 changes" control shows the next 200 (the unchanged entries' control reads "Show 200 more"), and its accessible name gives how many are not shown. Nested levels add up, so a nested level opens by default only while the first render stays under about 900 elements; one that would not starts closed behind a "Show N changes" control, and a level that runs out of budget shows fewer than 200 before its control.
  • Every control is a link-variant Button with a chevron, with Button's 44px hit region on a coarse pointer. A comparison of two large values therefore creates a bounded number of elements before anyone asks for more.
  • Identical values render the text "No differences".
  • Pass what JSON.stringify accepts. A circular reference, which JSON cannot hold, is walked to maxDepth and shows there as one changed entry.
Live preview

Nested changes

  • ~ schedule
    • ~ cron "0 2 * * *" → "0 3 * * *"
  • ~ steps
    • ~ 0
      • ~ retries 3 → 5
    • + 2 {2 keys}
  • - owner "data-platform"
  • + region "us-east-1"

02

When to use

Use when
  • Showing how two JSON values differ, such as one run's input against another's or a configuration before and after an edit.
  • Comparing structured payloads where which key or index changed matters more than line order.
Avoid when
03

Examples

Nested changes

Two versions of a run's input. Added, removed and changed entries show at every depth, each led by a +, - or ~ symbol; the unchanged entries stay behind a control until asked for.

Identical values

When the two values are equal the viewer says so instead of rendering an empty list.

A very long key

A property name of over 300 characters wraps inside its own column, so the viewer never scrolls sideways and the value stays on screen.

More than 200 changes in one level

A level shows its first 200 changed entries and holds the rest behind a control that shows 200 more. Here 450 values changed, so two presses reveal them all.

A comparison too large to open at once

Nested levels add up, so the first render opens a nested level only while the whole render stays small. Here five runs each changed 150 fields: the first run opens, and the rest wait behind a "Show 150 changes" control.

Controls on two levels

The settings level ends in its own "Show 2 unchanged entries" control, and the top level has one directly under it. On a touch screen each keeps its 44px target with room between them, so a tap on one never lands on the other.

A value that changes type

Arrays compare by index, so a changed item shows at its position. A value that changes type, here a number that becomes a string, shows as one removed and one added entry rather than one change.

Unchanged entries shown

Pressing "Show N unchanged entries" reveals what did not change, each row led by an = symbol, and the control reads "Hide" with its chevron turned up. The example presses the controls once on mount so the open state is visible.

04

Props

Props for json-diff-viewer
Name
Type
Default
Description
before required unknown The value to compare from. Any JSON-serializable structure.
after required unknown The value to compare to. Any JSON-serializable structure.
label text 'JSON differences' The accessible name of the comparison. Default "JSON differences".
maxDepth number 50 Hard depth cap. Collections nested deeper than this are compared whole and show as one changed entry, never walked. Default 50.