json-edit-react/README.md

React component for editing or viewing JSON/object data

<!-- The README that will appear on the package's NPM page: https://www.npmjs.com/package/json-edit-react
On publish, this file is temporarily renamed to the main README so it gets published to npm,
then renamed back to this file, so the primary README remains published to Github repo.

The {{BLOCKS}} below are replaced from the equivalent blocks in the main README file when the
`yarn prepareReadme` script is run (which also happens before publish).
 -->

<img width="60" alt="screenshot" src="image/logo192.png" style="float:left; margin-right: 1em;">

A highly-configurable [React](https://github.com/facebook/react) component for editing or viewing JSON/object data


## [Explore the Demo](https://carlosnz.github.io/json-edit-react/) <!-- omit in toc -->

![NPM Version](https://img.shields.io/npm/v/json-edit-react)
![GitHub License](https://img.shields.io/github/license/carlosnz/json-edit-react)
![NPM Downloads](https://img.shields.io/npm/dm/json-edit-react)

### Features include:

 - ✅ **Easy inline editing** of individual values or whole blocks of JSON text 
 - 🔒 **Granular control** – restrict edits, deletions, or additions per element
 - 📏 **[JSON Schema](https://json-schema.org/) validation** (using 3rd-party validation library)
 - 🎨 **Customisable UI** — built-in or custom [themes](https://github.com/CarlosNZ/json-edit-react#themes--styles), CSS overrides or targeted classes
 - 📦 **Self-contained** — plain HTML/CSS, so no dependence on external UI libraries
 - 🔍 **Search & filter** — find data by key, value or custom function
 - 🚧 **[Custom components](https://github.com/CarlosNZ/json-edit-react#custom-nodes)** — replace specific nodes with specialised components (e.g. date picker, links, images)
 - 🌏 **[Localisation](https://github.com/CarlosNZ/json-edit-react#localisation)** — easily translate UI labels and messages
 - 🔄 **[Drag-n-drop](https://github.com/CarlosNZ/json-edit-react#drag-n-drop)** re-ordering within objects/arrays
 - 🎹 **[Keyboard customisation](https://github.com/CarlosNZ/json-edit-react#keyboard-customisation)** — define your own key bindings
 - 🎮 **[External control](https://github.com/CarlosNZ/json-edit-react#external-control-1)** via callbacks and triggers

💡 Try the **[Live Demo](https://carlosnz.github.io/json-edit-react/)** to see these features in action!

<img width="392" alt="screenshot" src="image/screenshot.png">


<div style="background-color: #f6f8fa; border-left: 4px solid #d63384; padding: 15px; margin: 15px 0; border-radius: 3px;">
<p style="margin: 0 0 10px 0; color: #d63384;">
<strong>🚨 IMPORTANT:</strong>
</p>

Breaking changes:
- **Version 1.19.0** has a change to the `theme` input. Built-in themes must now be imported separately and passed in, rather than just naming the theme as a string. This is better for tree-shaking, so unused themes won't be bundled with your build. See [Themes & Styles](https://github.com/CarlosNZ/json-edit-react#themes--styles).
- **Version 1.14.0** has a change which recommends you provide a `setData` prop and not use `onUpdate` for updating your data externally. See [Managing state](https://github.com/CarlosNZ/json-edit-react#managing-state).
</div>

## Installation

```sh
# Depending on your package manager:

npm i json-edit-react
# OR
yarn add json-edit-react
```

## Implementation

```jsx
import { JsonEditor } from 'json-edit-react'

// In your React component:
return (
  <JsonEditor
    data={ jsonData }
    setData={ setJsonData } // optional
    { ...otherProps } />
);
```

## Usage

**(for end user)**

It's pretty self explanatory (click the "edit" icon to edit, etc.), but there are a few not-so-obvious ways of interacting with the editor:

- **Double-click** a value (or a key) to edit it
- When editing a string, use `Cmd/Ctrl/Shift-Enter` to add a new line (`Enter` submits the value)
- It's the opposite when editing a full object/array node (which you do by **clicking "edit"** on an object or array value) — `Enter` for new line, and `Cmd/Ctrl/Shift-Enter` for submit
- `Escape` to **cancel** editing
- When clicking the "**clipboard**" icon, holding down `Cmd/Ctrl` will copy the *path* to the selected node rather than its value
- When opening/closing a node, hold down "Alt/Option" to open/close *all* child nodes at once
- For Number inputs, **arrow-up** and **down** keys will increment/decrement the value
- For Boolean inputs, **space bar** will toggle the value
- Easily navigate to the next or previous node for editing using the `Tab`/`Shift-Tab` keys.
- **Drag and drop** items to change the structure or modify display order
- When editing is not permitted, double-clicking a string value will expand the text to the full value if it is truncated due to length (there is also a clickable "..." for long strings)
- **JSON text input** can accept "looser" input, if an additional JSON parsing method is provided (e.g. [JSON5](https://json5.org/)). See `jsonParse` prop.

[Have a play with the Demo app](https://carlosnz.github.io/json-edit-react/) to get a feel for it!

---

For **FULL DOCUMENTATION**, visit [https://github.com/CarlosNZ/json-edit-react](https://github.com/CarlosNZ/json-edit-react?tab=readme-ov-file#json-edit-react)