JSON Viewer React

A modern, lightweight React library for displaying and editing JSON data with an interactive tree interface. Perfect for debugging, data visualization, and JSON editing in React applications.

✨ Features

• 🌳 Interactive JSON tree view with expand/collapse functionality
• 🔍 Search and highlight with auto-expand matching nodes
• ✏️ Inline editing with validation and error handling
• 📋 Copy operations for values and paths
• 🎨 Customizable themes (light/dark) with CSS variables
• 📱 Responsive design with mobile support
• ♿ Accessibility support with keyboard navigation
• 🔧 Full TypeScript support with comprehensive type definitions
• 📦 Small bundle size (<10KB gzipped)
• ⚡ Performance optimized with safety limits and memoization

📦 Installation

npm install @rio2k2/json-viewer-react

yarn add @rio2k2/json-viewer-react

pnpm add @rio2k2/json-viewer-react

🚀 Quick Start

import React from 'react';
import { JSONViewer } from '@rio2k2/json-viewer-react';
import '@rio2k2/json-viewer-react/styles';

const data = {
  name: "John Doe",
  age: 30,
  isActive: true,
  hobbies: ["reading", "coding", "gaming"],
  address: {
    street: "123 Main St",
    city: "New York",
    zipCode: "10001"
  }
};

function App() {
  return (
    <JSONViewer 
      data={data} 
      theme="light"
      editable={true}
      showTypes={true}
      onChange={(path, oldValue, newValue) => {
        console.log('Value changed:', { path, oldValue, newValue });
      }}
    />
  );
}

📖 API Reference

JSONViewer Props

Prop	Type	Default	Description
data	object | string	required	JSON data to display
rootName	string	"root"	Name for the root node
collapsed	boolean | number	false	Initial collapse state or depth
editable	boolean	false	Enable inline editing
search	string	undefined	Controlled search value
showTypes	boolean	true	Show type badges
theme	'light' | 'dark' | string	"light"	Theme or custom class
maxRenderDepth	number	6	Maximum render depth
maxNodes	number	2000	Maximum nodes to render
className	string	undefined	Additional CSS class
style	React.CSSProperties	undefined	Inline styles

Event Handlers

Prop	Type	Description
onSelect	(path: string, node: NodeMeta) => void	Called when a node is selected
onChange	(path: string, oldVal: any, newVal: any) => void	Called when a value is edited
onError	(error: Error) => void	Called when an error occurs
onSearchMatchCount	(count: number) => void	Called with search match count

Custom Renderers

Prop	Type	Description
renderValue	(value: any, path: string) => ReactNode	Custom value renderer
renderKey	(key: string, path: string) => ReactNode	Custom key renderer

Imperative API

Use a ref to access imperative methods:

import React, { useRef } from 'react';
import { JSONViewer, JSONViewerHandle } from '@rio2k2/json-viewer-react';

function App() {
  const viewerRef = useRef<JSONViewerHandle>(null);

  const handleExpandAll = () => {
    viewerRef.current?.expandAll();
  };

  const handleCollapseAll = () => {
    viewerRef.current?.collapseAll();
  };

  const handleSearch = () => {
    viewerRef.current?.search('John');
  };

  return (
    <div>
      <button onClick={handleExpandAll}>Expand All</button>
      <button onClick={handleCollapseAll}>Collapse All</button>
      <button onClick={handleSearch}>Search "John"</button>
      
      <JSONViewer 
        ref={viewerRef}
        data={data} 
      />
    </div>
  );
}

Available Methods

Method	Description
expandAll()	Expand all nodes
collapseAll()	Collapse all nodes
search(query: string)	Search for a query
get(path: string)	Get value at path
set(path: string, value: any)	Set value at path
toJSON()	Get current JSON data

🎨 Theming

Built-in Themes

// Light theme (default)
<JSONViewer data={data} theme="light" />

// Dark theme
<JSONViewer data={data} theme="dark" />

// Custom theme class
<JSONViewer data={data} theme="my-custom-theme" />

CSS Variables

Customize the appearance using CSS variables:

.jv-theme-custom {
  --jv-bg-color: #f8f9fa;
  --jv-text-color: #212529;
  --jv-key-color: #0066cc;
  --jv-string-color: #22863a;
  --jv-number-color: #005cc5;
  --jv-boolean-color: #d73a49;
  --jv-null-color: #6f42c1;
  --jv-border-color: #e1e4e8;
  --jv-hover-bg: #f1f8ff;
  --jv-focus-border: #0366d6;
}

🔍 Advanced Examples

Controlled Search

function SearchableViewer() {
  const [searchQuery, setSearchQuery] = useState('');
  const [matchCount, setMatchCount] = useState(0);

  return (
    <div>
      <input
        type="text"
        value={searchQuery}
        onChange={(e) => setSearchQuery(e.target.value)}
        placeholder="Search JSON..."
      />
      <span>Matches: {matchCount}</span>
      
      <JSONViewer
        data={data}
        search={searchQuery}
        onSearchMatchCount={setMatchCount}
      />
    </div>
  );
}

Custom Value Renderer

function CustomViewer() {
  const renderValue = (value: any, path: string) => {
    if (typeof value === 'string' && value.startsWith('http')) {
      return <a href={value} target="_blank" rel="noopener noreferrer">{value}</a>;
    }
    return null; // Use default renderer
  };

  return (
    <JSONViewer
      data={data}
      renderValue={renderValue}
    />
  );
}

Large Data Handling

<JSONViewer
  data={largeData}
  maxRenderDepth={3}
  maxNodes={1000}
  collapsed={2}
  onError={(error) => console.error('JSON Viewer Error:', error)}
/>

🧪 TypeScript Support

The library is written in TypeScript and provides comprehensive type definitions:

import { 
  JSONViewer, 
  JSONViewerHandle, 
  JSONViewerProps,
  NodeMeta,
  JSONPath 
} from '@rio2k2/json-viewer-react';

interface MyData {
  id: number;
  name: string;
  metadata: Record<string, any>;
}

const data: MyData = {
  id: 1,
  name: "Example",
  metadata: { version: "1.0" }
};

const handleChange = (path: JSONPath, oldValue: any, newValue: any) => {
  // Type-safe change handling
};

🚀 Performance Tips

1. Use collapsed prop for large datasets to avoid rendering all nodes initially
2. Set maxRenderDepth to limit deep nesting rendering
3. Set maxNodes to prevent browser freezing with huge datasets
4. Use React.memo when wrapping JSONViewer in your components
5. Debounce search input for better performance with large datasets

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © locnv2k2

🔗 Links

• Demo
• GitHub
• Issues

Configuration

The config prop accepts the following options:

• editable (boolean): Enable inline editing of values
• showTypes (boolean): Show type badges for values
• theme ('light' | 'dark'): Color theme
• maxRenderDepth (number): Maximum depth to render (default: 6)
• maxNodes (number): Maximum number of nodes to render (default: 2000)
• rootName (string): Name for the root node (default: 'root')

Event Handlers

• onSelect: Called when a node is selected
• onChange: Called when a value is edited
• onError: Called when an error occurs

Custom Renderers

You can provide custom renderers for keys and values:

<JSONViewer 
  data={data}
  renderKey={(key, path) => <strong>{key}</strong>}
  renderValue={(value, path) => {
    if (typeof value === 'string' && value.startsWith('http')) {
      return <a href={value}>{value}</a>;
    }
    return null; // Use default renderer
  }}
/>

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build

# Run type checking
npm run check

License

MIT License - see LICENSE file for details.

json-viewer-react