A React.js component based on the json-diff package
A [React.js] component that renders a structural diff of two JSON values. Written in TypeScript
except for the JavaScript code inherited from the original [json-diff] library.
Types are declared for all user facing functionality.
This is a fork of [json-diff] with all of the dependencies towards Node.js core modules removed.
Code from [json-diff] can be found under src/JsonDiff/Internal and it’s mostly unchanged — expect
for the colorize module which now returns a JSX element instead of a string.
See the interactive live demo.
Also see the source of that demo.
!A screenshot of the React component example
Also see https://relex.github.io/json-diff-react/ for other examples.
Here is a simple example (see the full demo of this example):
`` typescript
function DiffOfJsons({ a, b }: { a: string, b: string }): JSX.Element {
try {
// JSON.parse() can throw an exception if parsing fails.
// It’s for you to handle them before calling
const parsedA = JSON.parse(a)
const parsedB = JSON.parse(b);
return
jsonB={parsedB}
styleCustomization={{
additionLineStyle: { color: 'green' },
deletionLineStyle: { color: 'red' },
unchangedLineStyle: { color: 'gray' },
frameStyle: {
'font-family': 'monospace',
'white-space': 'pre',
'background': 'silver',
},
}}
/>;
} catch (e: any) {
return
Error: {e?.message ?? JSON.stringify(e)}
;Look into the examples directory to find more examples on how to use this component.
Usage
The
requires 4 input properties:1.
jsonA (required): a JSON value
- The caller is responsible for providing a valid, parsed JSON value (e.g. via JSON.parse)
2. jsonB (required): a JSON value that is compared to jsonA
- The caller is responsible for providing a valid, parsed JSON value
3. styleCustomization (optional): CSS customization of the markup
4. jsonDiffOptions (optional): options that are fed directly to original [json-diff] codeN.B. The type of the input JSON values is described in TypeScript like this (you can import this
type from the library in case you need to use it for the values passed to the
):` typescript
export type JsonValue =
| { [x: string]: JsonValue }
| Array
| string
| number
| boolean
| null;
`$3
There are two ways to customize the look of the component:
1. via CSS styles
2. via
styleCustomization property of #### CSS
Add these CSS styles for the component and customize them:
` css
.deletion {
/ customization for deleted lines () /
color: red;
}.addition {
/ customization for added lines () /
color: green;
}.unchanged {
/ customization for unchanged lines () /
color: gray;
}.diff {
/ customization for the top-level wrapper that contains the diff /
font-family: monospace;
white-space: pre;
}
`The names of the classes can be customized via
styleCustomization React property.#### styleCustomization
You can also use the
styleCustomization property to customize how the
component looks and rename the CSS classes.` typescript
export type StyleCustomization = {
additionLineStyle: CSS.Properties | null;
additionClassName: string | null | undefined;
deletionLineStyle: CSS.Properties | null;
deletionClassName: string | null | undefined;
unchangedLineStyle: CSS.Properties | null;
unchangedClassName: string | null | undefined;
frameStyle: CSS.Properties | null;
frameClassName: string | null | undefined;
};
`Explanation of each customization option:
*
additionLineStyle: style attribute of the HTML element that is
used to render added lines in the diff
* Defaults to null if not specified (means there will be no style added)
* additionClassName: className attribute of the HTML element that
is used to render added lines in the diff
* Defaults to addition if not specified
* Set to null to remove the class attribute
* deletionLineStyle: style attribute of the HTML element that is
used to render deleted lines in the diff
* Defaults to null if not specified (means there will be no style added)
* deletionClassName: className attribute of the HTML element that
is used to render deleted lines in the diff
* Defaults to deletion if not specified
* Set to null to remove the class attribute
* unchangedLineStyle: style attribute of the HTML element that is
used to render unchanged lines in the diff
* Defaults to null if not specified (means there will be no style added)
* unchangedClassName: className attribute of the HTML element that
is used to render unchanged lines in the diff
* Defaults to unchanged if not specified
* Set to null to remove the class attribute
* frameStyle: style attribute of the HTML element that contains the
whole rendered diff, i.e. the top level
* Can be used to customize background, etc.
* Defaults to null if not specified (means there will be no style added)
* frameClassName: className attribute of the HTML element that
contains the whole rendered diff, i.e. the top level
* Defaults to diff
* Set to null to remove the class attribute
$3
You can pass options to the underlying [json-diff] functions via
jsonDiffOptions which has the following type:` typescript
export interface DiffOptions {
verbose?: boolean;
raw?: boolean;
keysOnly?: boolean;
full?: boolean;
sort?: boolean;
outputKeys?: string[];
keepUnchangedValues?: boolean;
outputNewOnly?: boolean;
maxElisions?: number;
precision?: number;
excludeKeys?: string[];
showElisionsForObjects?: boolean;
renderElision?: (elisionCount: number, maxElisions: number) => string | string[];
}
`All of the fields are optional. Consult the original [json-diff] library to
learn more about how the options impact the output.
Most of the
DiffOptions type came from
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/json-diff/index.d.ts.N.B. I added the
excludeKeys attribute to the DiffOptions imported from
DefinitelyTyped. It appears like the type definitions in DefinitelyTyped
are outdated.N.B.
showElisionsForObjects option was not part of the original [json-diff] library.
It was added only for this library. It’s turned on by default.
It renders elisions like ... for objects in the similar way it’s done for arrays.N.B.
renderElision` option was added only to this library.
It wasn’t a part of original [json-diff] library.
It allows you to customize “...”/“... (N entries)” template.
Can also be useful to support localizations other than English.Authors
Thanks to Andrey Tarantsov for the work he did on the original [json-diff] package.
This package is just a thin wrapper on top of it.
Thanks to Viacheslav Lotsmanov for providing code review and change suggestions.
This package was built at RELEX.
Main developer: Joonas Laukka.
License
This software is distributed under the MIT license.
For details, have a look at LICENSE-MIT.
[json-diff]: https://github.com/andreyvit/json-diff
[React.js]: https://reactjs.org