0
# React JSON Tree
1

2
React JSON Tree is a React component for visualizing JSON data structures in an interactive tree format. It supports collapsible/expandable nodes, custom themes based on base16 color schemes, and advanced JavaScript data types including Immutable.js collections and other iterable objects.
3

4
## Package Information
5

6
- **Package Name**: react-json-tree
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-json-tree`
10

11
## Core Imports
12

13
```typescript
14
import { JSONTree } from "react-json-tree";
15
import type { 
16
  Key, 
17
  KeyPath, 
18
  GetItemString, 
19
  LabelRenderer, 
20
  ValueRenderer,
21
  ShouldExpandNodeInitially,
22
  PostprocessValue,
23
  IsCustomNode,
24
  SortObjectKeys,
25
  Styling,
26
  CommonExternalProps,
27
  StylingValue
28
} from "react-json-tree";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const { JSONTree } = require("react-json-tree");
35
```
36

37
## Basic Usage
38

39
```typescript
40
import { JSONTree } from "react-json-tree";
41

42
const data = {
43
  array: [1, 2, 3],
44
  bool: true,
45
  object: {
46
    foo: "bar"
47
  },
48
  string: "Hello World",
49
  number: 42,
50
  null: null
51
};
52

53
function App() {
54
  return <JSONTree data={data} />;
55
}
56
```
57

58
## Architecture
59

60
React JSON Tree is built around several key components:
61

62
- **JSONTree Component**: Main component that renders the interactive tree structure
63
- **Theme System**: Base16 theme support with light/dark variants and custom styling capabilities
64
- **Type Detection**: Automatic detection and handling of JavaScript data types including primitives, collections, and iterables
65
- **Rendering Pipeline**: Customizable renderers for labels, values, and collection previews
66
- **Expansion Control**: Configurable node expansion behavior with initial state control
67

68
## Capabilities
69

70
### JSONTree Component
71

72
The main component for rendering JSON data as an interactive tree.
73

74
```typescript { .api }
75
interface JSONTreeProps extends Partial<CommonExternalProps> {
76
  /** The JSON data to display */
77
  data: unknown;
78
  /** Base16 theme or custom styling configuration */
79
  theme?: Theme;
80
  /** Whether to invert the theme colors (light/dark mode toggle) */
81
  invertTheme?: boolean;
82
}
83

84
function JSONTree(props: JSONTreeProps): React.ReactElement;
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
// Basic usage
91
<JSONTree data={myData} />
92

93
// With theme
94
<JSONTree 
95
  data={myData} 
96
  theme={{
97
    scheme: 'monokai',
98
    base00: '#272822',
99
    base01: '#383830',
100
    // ... other base16 colors
101
  }}
102
/>
103

104
// With theme inversion
105
<JSONTree data={myData} theme={myTheme} invertTheme={true} />
106
```
107

108
### Customization Options
109

110
React JSON Tree provides extensive customization through the CommonExternalProps interface.
111

112
```typescript { .api }
113
interface CommonExternalProps {
114
  /** Path to the root node, defaults to ['root'] */
115
  keyPath: KeyPath;
116
  /** Custom function to render property labels */
117
  labelRenderer: LabelRenderer;
118
  /** Custom function to render values */
119
  valueRenderer: ValueRenderer;
120
  /** Function to determine initial node expansion */
121
  shouldExpandNodeInitially: ShouldExpandNodeInitially;
122
  /** Hide the root node wrapper */
123
  hideRoot: boolean;
124
  /** Custom function to render collection previews */
125
  getItemString: GetItemString;
126
  /** Function to preprocess values before rendering */
127
  postprocessValue: PostprocessValue;
128
  /** Function to override default object type detection */
129
  isCustomNode: IsCustomNode;
130
  /** Maximum number of items to show before collapsing ranges */
131
  collectionLimit: number;
132
  /** Sort object keys (boolean for default sort, function for custom) */
133
  sortObjectKeys: SortObjectKeys;
134
}
135
```
136

137
**Custom Label Rendering:**
138

139
```typescript
140
<JSONTree
141
  data={data}
142
  labelRenderer={([key]) => <strong style={{color: 'blue'}}>{key}</strong>}
143
/>
144
```
145

146
**Custom Value Rendering:**
147

148
```typescript
149
<JSONTree
150
  data={data}
151
  valueRenderer={(raw, value) => <em>{String(raw)}</em>}
152
/>
153
```
154

155
**Custom Collection Preview:**
156

157
```typescript
158
<JSONTree
159
  data={data}
160
  getItemString={(type, data, itemType, itemString) => (
161
    <span>// {type} with {itemString}</span>
162
  )}
163
/>
164
```
165

166
**Initial Expansion Control:**
167

168
```typescript
169
<JSONTree
170
  data={data}
171
  shouldExpandNodeInitially={(keyPath, data, level) => level < 2}
172
/>
173
```
174

175
**Object Key Sorting:**
176

177
```typescript
178
// Default alphabetical sorting
179
<JSONTree data={data} sortObjectKeys={true} />
180

181
// Custom sorting
182
<JSONTree 
183
  data={data} 
184
  sortObjectKeys={(a, b) => String(a).localeCompare(String(b), undefined, {numeric: true})}
185
/>
186
```
187

188
### Advanced Customization
189

190
```typescript { .api }
191
/** Theme type from react-base16-styling - can be a Base16Theme or custom styling object */
192
type Theme = Base16Theme | { [styleName: string]: any };
193

194
/** Complete Base16 theme interface */
195
interface Base16Theme {
196
  scheme: string;
197
  author: string;
198
  base00: string; // Default Background
199
  base01: string; // Lighter Background
200
  base02: string; // Selection Background
201
  base03: string; // Comments, Invisibles
202
  base04: string; // Dark Foreground
203
  base05: string; // Default Foreground
204
  base06: string; // Light Foreground
205
  base07: string; // Light Background
206
  base08: string; // Variables, XML Tags
207
  base09: string; // Integers, Boolean, Constants
208
  base0A: string; // Classes, Markup Bold
209
  base0B: string; // Strings, Inherited Class
210
  base0C: string; // Support, Regular Expressions
211
  base0D: string; // Functions, Methods, Attribute IDs
212
  base0E: string; // Keywords, Storage, Selector
213
  base0F: string; // Deprecated, Opening/Closing Tags
214
}
215

216
/** Custom theme with style overrides */
217
interface CustomTheme extends Partial<Base16Theme> {
218
  extend?: Theme;
219
  [styleName: string]: any;
220
}
221
```
222

223
**Advanced Theme Customization:**
224

225
```typescript
226
<JSONTree
227
  data={data}
228
  theme={{
229
    extend: baseTheme,
230
    // Custom styles for specific elements
231
    valueLabel: {
232
      textDecoration: 'underline'
233
    },
234
    nestedNodeLabel: ({ style }, keyPath, nodeType, expanded) => ({
235
      style: {
236
        ...style,
237
        textTransform: expanded ? 'uppercase' : style.textTransform
238
      }
239
    })
240
  }}
241
/>
242
```
243

244
## Types
245

246
### Core Types
247

248
```typescript { .api }
249
/** Type for object keys or array indices */
250
type Key = string | number;
251

252
/** Array representing the path to a nested value */
253
type KeyPath = readonly (string | number)[];
254

255
/** Styling function from react-base16-styling */
256
type Styling = StylingFunction;
257

258
/** Styling value type from react-base16-styling */
259
type StylingValue = unknown;
260
```
261

262
### Renderer Function Types
263

264
```typescript { .api }
265
/** Function to customize collection preview display */
266
type GetItemString = (
267
  nodeType: string,
268
  data: unknown,
269
  itemType: React.ReactNode,
270
  itemString: string,
271
  keyPath: KeyPath,
272
) => React.ReactNode;
273

274
/** Function to customize property label rendering */
275
type LabelRenderer = (
276
  keyPath: KeyPath,
277
  nodeType: string,
278
  expanded: boolean,
279
  expandable: boolean,
280
) => React.ReactNode;
281

282
/** Function to customize value rendering */
283
type ValueRenderer = (
284
  valueAsString: unknown,
285
  value: unknown,
286
  ...keyPath: KeyPath
287
) => React.ReactNode;
288

289
/** Function to determine initial node expansion */
290
type ShouldExpandNodeInitially = (
291
  keyPath: KeyPath,
292
  data: unknown,
293
  level: number,
294
) => boolean;
295

296
/** Function to preprocess values before rendering */
297
type PostprocessValue = (value: unknown) => unknown;
298

299
/** Function to override default object type detection */
300
type IsCustomNode = (value: unknown) => boolean;
301

302
/** Sorting function for object keys or boolean for default sorting */
303
type SortObjectKeys = ((a: unknown, b: unknown) => number) | boolean;
304
```
305

306
## Supported Data Types
307

308
React JSON Tree automatically detects and handles all JavaScript data types:
309

310
- **Primitives**: `string`, `number`, `boolean`, `null`, `undefined`
311
- **Objects**: Plain objects, custom class instances
312
- **Arrays**: Regular arrays with numeric indices
313
- **Functions**: Function objects (displayed as `[Function]`)
314
- **Symbols**: Symbol values
315
- **Dates**: Date objects with formatted display
316
- **Errors**: Error objects with message display
317
- **Collections**: `Map`, `Set`, `WeakMap`, `WeakSet`
318
- **Iterables**: Any object implementing the iterable protocol (including Immutable.js collections)
319

320
## Theme System
321

322
React JSON Tree uses the base16 theming system from react-base16-styling. The Base16Theme interface (defined above in Advanced Customization) provides 16 color slots for consistent theming.
323

324
**Built-in Default Theme:**
325

326
The package includes a built-in Solarized theme as the default, providing good contrast and readability. When no theme is provided, this default theme is automatically applied.
327

328
## Performance Features
329

330
- **Collection Limiting**: Large arrays and objects are automatically paginated using the `collectionLimit` prop (default: 50 items)
331
- **Lazy Expansion**: Nodes are only rendered when expanded, improving performance for large datasets
332
- **Efficient Re-rendering**: Uses React's reconciliation to minimize DOM updates
333
- **Memory Optimization**: Circular reference detection prevents infinite loops