React JSON Editor Component

Common errors

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

  cause This error often occurs when the `JsonEditor` component is imported incorrectly or when the `theme` prop receives an invalid value (e.g., a string instead of an imported theme object after v1.19.0).
  fix Ensure `import { JsonEditor } from 'json-edit-react';` is correct. If using themes, verify that `import { yourThemeName } from 'json-edit-react/themes';` is used and the theme object is passed as `{theme={yourThemeName}}`.

• Cannot read properties of undefined (reading 'map') or 'forEach'

  cause Often indicates that the `data` prop passed to `JsonEditor` is `undefined`, `null`, or not a valid object/array when the component expects one, especially during initial render or asynchronous data loading.
  fix Ensure the `data` prop always receives a valid JavaScript object or array. Initialize your state with an empty object `{}` or array `[]` if the data is fetched asynchronously, or conditionally render the `JsonEditor` component only when `data` is available.

• Unhandled Runtime Error: A component is changing an uncontrolled input of type [text/number] to be controlled. Input elements should not switch from uncontrolled to controlled (or vice versa).

  cause While less common directly from `json-edit-react`, this can arise if an external state update (e.g., from `setData`) interferes with an internal input element's state within the editor, especially if `data` is mutated directly rather than creating a new object.
  fix Ensure that any updates to the `data` prop passed to `JsonEditor` are done immutably (e.g., using spread syntax `...` to create new objects/arrays) to avoid unexpected re-renders or state conflicts. The `setData` prop provided by `json-edit-react` typically handles this correctly.

Warnings

• breaking The way themes are applied changed in v1.19.0. Instead of passing a theme name as a string (e.g., `theme="dark"`), you must now explicitly import the theme object and pass it (e.g., `theme={darkTheme}`). This change was implemented for better tree-shaking.
  Fix: Replace `theme="yourThemeName"` with `import { yourThemeName } from 'json-edit-react/themes';` and then `theme={yourThemeName}`.
• gotcha When handling data updates, it is recommended to use the `setData` prop for external updates rather than relying solely on the `onUpdate` prop, especially since v1.14.0. This ensures proper state management within React.
  Fix: Pass a `setData` prop that updates your component's state (e.g., using `useState`'s setter) with the new data object provided by the editor.
• gotcha Displaying and editing very large JSON objects (e.g., hundreds of thousands of keys/values or deeply nested structures) can lead to performance issues due to React's rendering cycle and the component's interactive features. Users might experience UI lag.
  Fix: For extremely large datasets, consider debouncing `setData` calls, implementing virtualized lists if possible, or using server-side processing for complex operations. Limit the initial `collapsed` depth or use `shouldExpandNodeInitially` to prevent rendering a massive DOM tree upfront.
• gotcha The `json-edit-react` component, while flexible, may not automatically handle custom object types (like `Date`, `Map`, `Set`) as distinct editable entities without explicit configuration. By default, these might be stringified or treated as plain objects, potentially losing type fidelity.
  Fix: Utilize the `customComponents` prop to provide specific React components for rendering and editing non-standard data types. Also, explore options like `handleCustomCollections` (since v1.27.0) to treat custom objects as 'Value' nodes.
• gotcha The v1.29.0 release introduced an option for '1-indexed arrays' display. If enabled, this changes how array indices are presented in the UI (starting from 1 instead of 0), which might confuse users accustomed to 0-indexed arrays in programming contexts. It is a display-only option and does not change the underlying data structure.
  Fix: If 0-indexed display is preferred, ensure the `arraysIndexFrom1` prop (or similar configuration) is explicitly set to `false` or left at its default value if it defaults to `false`. Communicate this display choice to end-users if it deviates from standard programming conventions.

Install

• npm install json-edit-react npm
• yarn add json-edit-react yarn
• pnpm add json-edit-react pnpm

Imports

• JsonEditor
  wrong:

  const JsonEditor = require('json-edit-react');

  correct:

  import { JsonEditor } from 'json-edit-react';

  Main component for JSON editing/viewing. While CommonJS might work in some setups, modern React applications generally use ES Modules.
• BuiltInThemes
  wrong:

  import { 'dark' } from 'json-edit-react/themes';

  correct:

  import { BuiltInThemes } from 'json-edit-react';

  Since v1.19.0, built-in themes must be imported explicitly rather than referenced by string name, improving tree-shaking.
• JsonEditorProps

  import type { JsonEditorProps } from 'json-edit-react';

  TypeScript type definition for the component's props, useful for type-checking and IDE assistance.

Quickstart

This quickstart demonstrates rendering an editable JSON structure, updating state, applying a built-in theme, and configuring basic editing restrictions using a functional React component.

import React, { useState, useCallback } from 'react';
import { JsonEditor } from 'json-edit-react';
// Import a built-in theme (since v1.19.0)
import { darkTheme } from 'json-edit-react/themes';

function MyJsonEditorComponent() {
  const [jsonData, setJsonData] = useState({
    user: {
      id: 1,
      name: "Alice Smith",
      email: "alice@example.com",
      isActive: true,
      roles: ['admin', 'editor'],
      settings: {
        theme: 'dark',
        notifications: true,
        dataLimit: 1000
      }
    },
    products: [
      { id: 'a1', name: 'Laptop', price: 1200 },
      { id: 'b2', name: 'Mouse', price: 25 }
    ]
  });

  // Callback to handle changes from the editor
  const handleDataChange = useCallback((updatedData) => {
    console.log('JSON data updated:', updatedData);
    setJsonData(updatedData);
  }, []);

  return (
    <div style={{ maxWidth: '800px', margin: '20px auto', padding: '20px', border: '1px solid #ccc', borderRadius: '8px' }}>
      <h2>Interactive JSON Data</h2>
      <JsonEditor
        data={jsonData}
        setData={handleDataChange}
        restrictAdd={(path, value) => path.length < 3} // Example: only allow adding at root or first level
        restrictDelete={(path) => path[0] !== 'products'} // Example: prevent deleting top-level 'products'
        rootName="MyAppData"
        theme={darkTheme}
        highlightUpdates={true}
        showArrayIndices={true}
        showObjectSize={true}
      />
      <pre style={{ marginTop: '20px', backgroundColor: '#eee', padding: '10px', borderRadius: '4px' }}>
        <code>{JSON.stringify(jsonData, null, 2)}</code>
      </pre>
    </div>
  );
}

export default MyJsonEditorComponent;