# json-edit-react
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/)
[](https://deepwiki.com/CarlosNZ/json-edit-react)
[](https://github.com/CarlosNZ/json-edit-react/discussions)
[](https://github.com/sponsors/CarlosNZ)
### 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](#appearance--theming), CSS overrides or targeted classes
- ๐ฆ **Self-contained** โ plain HTML/CSS, no external UI library dependencies, and *zero runtime dependencies*
- ๐ **Search & filter** โ find data by key, value or custom function
- ๐ง **[Custom components](#custom-nodes--components)** โ replace keys and/or values with specialised components (e.g. date picker, links, images, `undefined`, `BigInt`, `Symbol`)
- ๐ **[Localisation](#localisation)** โ easily translate UI labels and messages
- ๐ **[Drag-n-drop](#drag-and-drop-reordering)** re-ordering within objects/arrays
- ๐น **[Keyboard customisation](#keyboard-control)** โ define your own key bindings
- ๐ฎ **[External control](#programmatic-control)** via callbacks and imperative methods
๐ก Try the **[Live Demo](https://carlosnz.github.io/json-edit-react/)** to see these features in action!
> [!IMPORTANT]
> This documentation is for V2 of **json-edit-react**. Looking for V1? See the [V1 docs](https://github.com/CarlosNZ/json-edit-react/tree/v1.x#readme) and [V1 demo](https://carlosnz.github.io/json-edit-react-v1/).
>
> If you're upgrading from V1, be sure to read the [migration guide](https://github.com/CarlosNZ/json-edit-react/blob/main/migration-guide.md).
>
> ๐ค๏ธ Got feedback? [Open an issue](https://github.com/CarlosNZ/json-edit-react/issues), or join the conversation in [Discussions](https://github.com/CarlosNZ/json-edit-react/discussions/categories/announcements).
## Optional Companion Packages
- **THEMES**: [@json-edit-react/themes](https://www.npmjs.com/package/@json-edit-react/themes) โ curated, ready-made [themes](#using-a-prebuilt-theme-json-edit-reactthemes)
- **COMPONENTS**: [@json-edit-react/components](https://www.npmjs.com/package/@json-edit-react/components) - custom node components (links, date picker, etc.)
- **UTILITIES**: [@json-edit-react/utils](https://www.npmjs.com/package/@json-edit-react/utils) โย a collection of helpers and tools for extending and streamlining your **json-edit-react** experience
----
## Contents
- [Using the editor (for end users)](#using-the-editor-for-end-users)
- [Installation](#installation)
- [Implementation](#implementation)
- [Props Reference](#props-reference)
- [Managing state](#managing-state)
- [Filter Functions](#filter-functions)
- [Controlling editing](#controlling-editing)
- [Reacting to changes](#reacting-to-changes)
- [Appearance \& theming](#appearance--theming)
- [Initial expansion โ `collapse`](#initial-expansion--collapse)
- [Search \& filtering](#search--filtering)
- [Localisation](#localisation)
- [Keyboard control](#keyboard-control)
- [Custom Nodes \& Components](#custom-nodes--components)
- [Overriding and extending the UI](#overriding-and-extending-the-ui)
- [Programmatic control](#programmatic-control)
- [Performance considerations](#performance-considerations)
- [Undo functionality](#undo-functionality)
- [Exported helpers \& types](#exported-helpers--types)
- [Issues \& support](#issues--support)
- [Inspiration](#inspiration)
- [Changelog](#changelog)
## Using the editor (for end users)
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-Enter or 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
- Use Tab/Shift-Tab to quickly move from one value to another when 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, the โ / โ arrow keys will increment/decrement the value
- For Boolean inputs, the 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!
## Installation
```sh
# Depending on your package manager:
npm i json-edit-react
# OR
yarn add json-edit-react
# OR
pnpm add json-edit-react
```
## Implementation
```jsx
import { JsonEditor } from 'json-edit-react'
// In your React component:
return (
);
// For a read-only viewer, use the `JsonViewer` component instead:
import { JsonViewer } from 'json-edit-react'
return
```
## Props Reference
`data` and `setData` are the only *required* props. For a read-only component, use [`JsonViewer`](#read-only-display--jsonviewer) instead โ its only required prop is `data`.
This is a reference list of *all* possible props, divided into related sections. Most of them provide a link to a section below in which the concepts are explored in more detail.
### Data Management
| Prop | Type | Default | Description |
| --------------------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | `object\|array` | - | The data to be displayed / edited |
| `setData` | `object\|array => void` | - | Method to update your `data` object. **Required.** See [Managing state](#managing-state) below for additional notes. |
| `onUpdate` | `UpdateFunction` | - | A function to run whenever a value is changed in the editor โ edit, add, delete, rename *or* move. See [Update functions](#onupdate--accept-reject-transform). |
| `onChange` | `OnChangeFunction` | - | A function to modify/constrain user input as they type โ see [OnChange functions](#onchange--validating-each-keystroke). |
| `onError` | `OnErrorFunction` | - | A function to run whenever the component reports an error โ see [OnErrorFunction](#onerror). |
| `showClipboardButton` | `boolean` | `true` | Show or hide the "Copy to clipboard" button in the UI. |
| `onCopy` | `OnCopyFunction` | - | A function to run whenever an item is **copied** to the clipboard โ see [Copy Function](#oncopy). |
### Restricting Editing
| Prop | Type | Default | Description |
| -------------------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowEdit` | `boolean\|FilterFunction` | `true` | If `false`, no editing at all is permitted. A callback function can be provided (return `true` to permit a given node) โ see [Advanced Editing Control](#filter-functions) |
| `allowDelete` | `boolean\|FilterFunction` | `true` | As with `allowEdit` but for deletion |
| `allowAdd` | `boolean\|FilterFunction` | `true` | As with `allowEdit` but for adding new properties |
| `allowTypeSelection` | `boolean\|TypeOptions\|TypeFilterFunction` | `true` | Controls which data types the user can select, including [Custom Node](#custom-nodes--components) types, and **Enums** โ see [Data Type Restrictions](#restricting-data-types--allowtypeselection) |
| `newKeyOptions` | `string[] \| NewKeyOptionsFunction` | - | New keys can be restricted to certain values โ see [New Key Restrictions & Default Values](#new-key-restrictions--default-values) |
| `defaultValue` | `any\|DefaultValueFunction` | `null` | Value that new properties are initialised with โ see [New Key Restrictions & Default Values](#new-key-restrictions--default-values) |
| `allowDrag` | `boolean\|FilterFunction` | `false` | Set to `true` to enable drag and drop functionality โ see [Drag-n-drop](#drag-and-drop-reordering) |
### Look and Feel / UI
| Prop | Type | Default | Description |
| ----------------------- | --------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `theme` | `ThemeInput` | `defaultTheme` | Either one of the built-in themes (imported separately), or an object specifying some or all theme properties โ see [Themes](#appearance--theming). |
| `showIconTooltips` | `boolean` | false | Display tooltips on the icon controls and the other labelled controls when hovering. |
| `indent` | `number` | `3` | Specify the amount of indentation for each level of nesting in the displayed data. |
| `collapse` | `boolean\|number\|FilterFunction` | `3` | Defines which depth level of the data tree will be displayed "expanded" in the UI on initial load โ see [Collapse](#initial-expansion--collapse). |
| `collapseAnimationTime` | `number` | `300` | Time (in ms) for the transition animation when collapsing collection nodes. |
| `collapseClickZones` | `Array<"left" \| "header" \| "property">` | `["left", "header"]` | Aside from the `โ` icon, you can specify other regions of the UI to be clickable for collapsing/opening a collection. |
| `rootName` | `string` | `"data"` | A name to display in the editor as the root of the data object. |
| `showArrayIndexes` | `boolean` | `true` | Whether or not to display the index (as a property key) for array elements. |
| `arrayIndexStart` | `0 \| 1` | `0` | The number the *first* array element's index label starts from. |
| `showStringQuotes` | `boolean` | `true` | Whether or not to display string values in "quotes". |
| `showCollectionCount` | `boolean\|"when-collapsed"\|"when-collapsed-or-filtered"` | `"when-collapsed-or-filtered"` | Whether or not to display the number of items in each collection (object or array). |
| `stringTruncateLength` | `number` | `250` | String values longer than this many characters will be displayed truncated (with `...`). The full string will always be visible when editing. |
| `sortKeys` | `boolean\|CompareFunction` | `false` | If `true`, object keys will be ordered (using default JS `.sort()`). A [compare function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) can also be provided to define sorting behaviour, except the input type should be a tuple of the key and the value of a node i.e. `(a: [string \| number, ValueData], b: [string \| number, ValueData]) => number` |
| `minWidth` | `number\|string` (CSS value) | `250` | Minimum width for the editor container. |
| `maxWidth` | `number\|string` (CSS value) | `600` | Maximum width for the editor container. |
| `baseFontSize` | `number\|string` (CSS value) | `16px` | The "base" font size from which all other sizings are derived (in `em`s). By changing this you will scale the entire component. |
| `insertAtTop` | `boolean\|"object"\|"array"` | `false` | If `true`, inserts new values at the *top* rather than bottom. Can set the behaviour just for arrays or objects by setting to `"object"` or `"array"` respectively. |
| `errorDisplayTime` | `number` | `2500` | Time (in ms) to display the error message in the UI. | |
| `showErrorMessages` | `boolean ` | `true` | Whether or not the component should display its own error messages (you'd probably only want to disable this if you provided your own [`onError` function](#onerror)) |
### Search and Filtering
| Prop | Type | Default | Description |
| -------------------- | --------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `searchText` | `string` | `undefined` | Data visibility will be filtered by matching against value, using the method defined below in `searchFilter` |
| `searchFilter` | `"key"\|"value"\|"all"\|SearchFilterFunction` | `undefined` | Define how `searchText` should be matched to filter the visible items โ see [Search/Filtering](#search--filtering) |
| `searchDebounceTime` | `number` | `350` | Debounce time when `searchText` changes |
### Custom components & overrides (incl. Localisation)
| Prop | Type | Default | Description |
| ----------------------- | --------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customNodeDefinitions` | `CustomNodeDefinition[]` | | You can provide custom React components to override specific nodes in the data tree, according to a condition function โ see [Custom nodes](#custom-nodes--components) or browse the [@json-edit-react/components](https://www.npmjs.com/package/@json-edit-react/components) |
| `customButtons` | `CustomButtonDefinition[]` | `[]` | You can add your own buttons to the Edit Buttons panel if you'd like to be able to perform a custom operation on the data โ see [Custom Buttons](#custom-buttons) |
| `translations` | `LocalisedStrings` | `{ }` | UI strings (such as error messages) can be translated by passing an object containing localised string values (there are only a few) โ see [Localisation](#localisation) |
| `customText` | `CustomTextDefinitions` | | In addition to [localising the component](#localisation) text strings, you can also *dynamically* alter them, depending on the data โ see [Custom Text](#dynamic-text--customtext) |
| `TextEditor` | `ReactComponent` `` | | Pass a component to offer a custom text/code editor when editing full JSON object as text. [See details](#replacing-the-textcode-editor--texteditor-codeeditor) |
| `Select` | `ReactComponent` `` | `` | Pass a component to replace the built-in native `
### External interaction
More detail [below](#programmatic-control)
| Prop | Type | Default | Description |
| ------------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEditEvent` | `OnEditEventFunction` | - | Callback for the full edit lifecycle โ `start`/`submit`/`commit`/`cancel`, the instant `delete`/`move`, and the background `updateSuccess`/`updateError` settlement โ see [Event callbacks](#listening-to-the-lifecycle--oneditevent) |
| `onCollapse` | `OnCollapseFunction` | - | Callback to execute whenever the user collapses or opens a node |
| `editorRef` | `Ref` | - | Imperative handle to collapse/open nodes or start/stop editing. See [Imperative handle](#driving-the-editor--the-editorref-handle) |
### Miscellaneous
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | - | Name for the HTML `id` attribute on the main component container. |
| `className` | `string` | - | Name of a CSS class to apply to the overall component. In most cases, specifying `theme` properties will be more straightforward. |
----
## Managing state
### Controlled component โ `data` + `setData`
You manage the `data` state yourself outside this component and pass in a `setData` method, which is called internally to update your `data`.
Keep the two channels distinct: **`data`/`setData` are your local UI state** (the document the editor renders and the setter it calls), while **`onUpdate` is for *external* writes and side effects** โ persisting to a server, validation, notifications, mutating-before-save. Don't reach for `onUpdate` to drive local state (that's `setData`'s job), and don't treat raw `setData` calls as "saves": under the [optimistic model](#async-updates--gating--hold) an *asynchronous* `onUpdate` lets `setData` fire for a value that's still in flight or about to be reverted, so anything that must react only to *settled* changes (autosave, an undo stack, a dirty flag) should key off `onUpdate` or the [`updateSuccess`/`updateError`](#listening-to-the-lifecycle--oneditevent) events, not raw `setData`.
### Read-only display โ `JsonViewer`
If your use case is read-only โ displaying JSON without any editing affordances โ import `JsonViewer` instead of `JsonEditor`:
```tsx
import { JsonViewer } from 'json-edit-react'
```
`JsonViewer` is a thin wrapper over `JsonEditor` that locks all edit, add, delete and drag operations off. It accepts the same display, theming, keyboard, search, collapse, localisation and custom-node props, but drops `setData`, the update callbacks (`onUpdate` / `onChange`), and the edit-permission props (`allowEdit` / `allowAdd` / `allowDelete` / `allowDrag` / `allowTypeSelection`) โ none of which are meaningful in a read-only context. Its `editorRef` handle (`JsonViewerHandle`) is collapse-only.
If you instead need an editor that *sometimes* locks editing (e.g. based on user permissions), keep using `` and toggle the relevant `allow*` props dynamically โ `allowEdit={canEdit}` etc.
[](https://carlosnz.github.io/json-edit-react/examples/json-viewer)
### Typed data โ `JsonEditor`
`JsonEditor` is generic on the type of its `data` prop, so TypeScript users can preserve their data shape across the component boundary instead of falling back to `unknown`:
```tsx
interface User {
name: string
email: string
roles: string[]
}
const [user, setUser] = useState(initialUser)
data={user}
setData={setUser}
onUpdate={({ newData }) => {
// newData is typed as User
}}
/>
```
The generic flows through `data`, `setData`, the `onUpdate` / `onChange` / `onError` callbacks (root data slots only โ per-node `value` stays `unknown`), and `NodeData.fullData` inside `FilterFunction`s. Defaults to `JsonData` (โ `unknown`) so untyped consumers don't need to change anything.
> [!TIP]
> `T` describes the data you *provide*. It is an input contract, not a runtime invariant โ if the user can freely restructure the JSON, post-edit values may not conform to `T`. Pair with `allowAdd` / `allowDelete` / `allowTypeSelection` to lock the shape, or validate inside `onUpdate` if you depend on it.
## Filter Functions
```jsx
// The powerhouse of the component
(nodeData) => result
```
The dynamic capabilities of the editor are powered by one core concept โ the `FilterFunction`. You provide a callback that receives a bunch of metadata about the current node, and it returns a boolean, or value, that determines what happens. Editing, search, styling, conditional rendering all rely on this workhorse structure, so we'll explain the shape of it here so you'll grasp how it's used throughout this doc.
| Type | Shape | Drives | Section |
| ----------------------- | ------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
| `FilterFunction` | `(nodeData) => boolean` | `allowEdit` / `allowDelete` / `allowAdd` / `allowDrag`, `collapse` | Controlling editing |
| `TypeFilterFunction` | `(nodeData) => boolean \| DataType[]` | `allowTypeSelection` | Controlling editing |
| `SearchFilterFunction` | `(nodeData, searchText) => boolean` | `searchFilter` | Search & filtering |
| `StyleFunction` | `(nodeData) => CSS \| null` | `theme` styles | Appearance & theming |
| `CustomTextFunction` | `(nodeData) => string \| null` | `customText` | Localisation |
| `condition` | `(nodeData) => boolean` | `customNodeDefinitions` | Custom nodes & components |
| `DefaultValueFunction` | `(nodeData, newKey?) => value` | `defaultValue` | Controlling editing |
| `NewKeyOptionsFunction` | `(nodeData) => string[] \| null` | `newKeyOptions` | Controlling editing |
The side-effect callbacks (`onUpdate` / `onChange` / `onError` / `onCollapse` / `onCopy` / `onEditEvent`) receive the **same** `NodeData` plus their own extras โ see [Reacting to changes](#reacting-to-changes) and [Programmatic control](#programmatic-control).
### The `NodeData` object
So what is this `nodeData` input? It's an object of the following shape:
```tsx
interface NodeData {
key: CollectionKey // name of the property (string or number (arrays))
path: CollectionKey[] // path to the property (as an array of property keys)
level: number // depth of the property (with 0 being the root)
index: number // index of the node within its collection (based on display order)
value: JsonData // value of the property
size: number | null // if a collection (object, array), the number of items
// (null for non-collections)
visibleSize?: number | null // direct-child count under the current search filter.
// - `number` on collections under an active filter;
// - `null` on render-path nodes when no filter is active
// or this isn't a tracked collection (e.g. a leaf).
// - `undefined` only inside the `searchFilter` callback
// itself (the walk hasn't computed counts yet) or when
// NodeData reaches you via an imperative bridge
// (onCollapse / onEditEvent / the editorRef handle).
// Use `!= null` to gate on "has a real count".
parentData: object | null // parent object containing the current node
fullData: JsonData // the full (overall) data object
collapsed?: boolean // whether or not the current node is in a
// "collapsed" state (only for Collection nodes)
}
```
Let's get into the many ways we can use this...
## Controlling editing
As well as configuring which nodes of can be **edited**, **deleted**, or **added** to, you can also specify:
- the data types (if any) available to each node (including *enums*),
- a restricted set of available keys that can be added to a node,
- default values for specific nodes and data types,
- drag 'n' drop restrictions
- which nodes appear open or closed ("collapsed")
As outlined in the [props list](#restricting-editing) above, most of these props can take either:
- a `boolean` (in which case `true` means the operation is fully permitted, `false` means it's fully disabled)
- a `FilterFunction` callback, which allows edit controls to be defined dynamically
The callback for each type of permission is slightly different, so let's look at each in turn:
### Permissions โ `allowEdit` / `allowDelete` / `allowAdd`
These each take a `boolean` value, or a [`FilterFunction`](#filter-functions) callback, which must return a boolean -- if `false` that node will **not** be editable (return `true` to permit it).
[](https://carlosnz.github.io/json-edit-react/examples/edit-restrictions)
> [!NOTE]
> There is no specific permission for editing object **property names**. Renaming a property is equivalent to deleting it and re-adding it under a new name in its parent collection, so a key is editable when the node returns `true` for `allowDelete` **and** its parent collection returns `true` for `allowAdd` (and the node isn't the root or an array index). `allowEdit` plays no part โ a key can be renamed even where its value can't. This mirrors a drag-and-drop [relocate](#drag-and-drop-reordering): a delete here, an add there.
### Restricting data types โ `allowTypeSelection`
The `allowTypeSelection` prop can take either a `boolean` (`false` means the data type can **not** be changed at all, `true` means any type is allowed) or a [`TypeFilterFunction`](#filter-functions), or an **array** of available data types. The core types are:
- `"string"`
- `"number"`
- `"boolean"`
- `"null"`
- `"object"`
- `"array"`
The data type array can also specify [Custom Node](#custom-nodes--components) types (as defined in the custom node's `name` prop), as well as **Enum** options (see [Enums](#enums) below).
The `TypeFilterFunction`, while it takes the same input shape as a standard `FilterFunction`, can return *either* a simple `boolean` *or* an `array` of available types.
> [!NOTE]
> If `allowTypeSelection` returns less than two available types for a given node, the "Type Selector" drop-down won't appear for that node.
[](https://carlosnz.github.io/json-edit-react/examples/type-restrictions)
### Enums
By defining an **Enum** type, you can restrict the available values to a pre-defined list:
To define an Enum, just add an object with the following structure to your "Types" array (either directly in the prop, or returned from the callback):
```js
{
enum: "My Enum Type" // name that will appear in the Types selector drop-down
values: [ // the list of allowed values
"Option A",
"Option B",
"Option C"
]
matchPriority: 1 // (Optional) used to recognize existing string values
// as the particular type (see below)
}
```
What is `matchPriority`? Well, when the data object is initialised, we have no way to know whether a given string value is "just a string" or is supposed to be one of the members of an Enum type (and we don't want to assume that if it's listed somewhere in an Enum `values` list that it definitely *should* be restricted to that type). So, if `matchPriority` is not defined, then that Enum type will *never* be initially assigned to a potentially matching Enum value when editing. If `matchPriority` is defined, then the highest priority Enum that has the value in its `values` list will be assigned (so if multiple Enums have overlapping `values`, the one with the highest priority will be applied.).
If the type of a given node is going to be *restricted* to a particular Enum type (i.e. the `allowTypeSelection` prop returns *only* one value), then a `matchPriority` is essential, otherwise it wouldn't be possible to switch a `string` to that type.
You can see examples of this in the [Star Wars data set](https://carlosnz.github.io/json-edit-react/?data=starWars) of the Demo โ the `eye_color`, `skin_color`, `hair_color` and `films` values are all restricted to a single, matching Enum type.
> [!NOTE]
> When editing, once an Enum type is selected from the Types selector, that node will continue to be displayed as that type for subsequent edits in the same session -- the `matchPriority` is purely for automatic recognition of a given value as a specific type when *first* editing it.
[](https://carlosnz.github.io/json-edit-react/examples/enums)
### New-key restrictions & default values
You can restrict the available properties a given collection node can have (when adding new properties) by setting the `newKeyOptions` prop. The value can be either a **list of keys**, or a [`NewKeyOptionsFunction`](#filter-functions) callback which returns the key list.
This will cause the UI to present a Drop-down selector when adding a new key rather than the usual text input:
The initial *value* for newly-added keys can also be defined with the `defaultValue` prop -- this can be *any* value, or a [`DefaultValueFunction`](#filter-functions) callback returning any value. The input signature is almost the same as standard `FilterFunctions`, but it can take a second argument, which is the name of the new key.
You can see an example of this in the [JSON Schema validation data](https://carlosnz.github.io/json-edit-react/?data=jsonSchemaValidation) of the Demo app when you add new keys to either the `address` collection or the root node.
[](https://carlosnz.github.io/json-edit-react/examples/new-key-restrictions)
### Drag-and-drop reordering
The `allowDrag` property controls which items (if any) can be dragged into new positions. By default, this is *off*, so you must set `allowDrag = true` to enable this functionality. Like the Edit permissions above, this property can also take a `FilterFunction` for fine-grained control. There are a couple of additional considerations, though:
- JavaScript does *not* guarantee object property order, so enabling this feature may yield unpredictable results. See [here](https://dev.to/frehner/the-order-of-js-object-keys-458d) for an explanation of how key ordering is handled.
> [!WARNING]
> It is strongly advised that you only enable drag-and-drop functionality if:
> 1. you're sure object keys will always be simple strings (i.e. not digits or non-standard characters)
> 2. you're saving the data in a serialisation format that preserves key order. For example, storing in a Postgres database using the `jsonb` (binary JSON) type, key order is meaningless, so the next time the object is loaded, the keys will be listed alphabetically.
- The `allowDrag` filter applies to the *source* node (the one being dragged) โ it controls whether a node can be **picked up** at all.
- What a drop is allowed to do then depends on where it lands, and reuses your existing permission filters โ so if you've configured restrictive editing constraints with Filter functions, they can't be circumvented via drag-n-drop:
| Drop | Is aโฆ | Requires |
| --- | --- | --- |
| Within the same collection | **reorder** | `allowEdit` on that collection |
| Into a *different* collection | **relocate** | `allowDelete` on the source **and** `allowAdd` on the destination collection |
A relocate is a delete-then-add across collections, so it needs both halves; a reorder changes nothing's membership, so it needs neither โ only that the collection itself is editable.
## Reacting to changes
### `onUpdate` โ accept, reject, transform
The **`onUpdate`** prop allows you to provide a callback that runs whenever the data changes in the editor โ for *every* kind of change. You might wish to use this to update some external state, post a notification, make an API call, modify the data before saving it, or [validate the data structure](#json-schema-validation) against a JSON schema. (It is *not* an alternative to `setData` โ see [Managing state](#managing-state).)
The function receives two arguments. The first is a single object, built on the standard [node data](#filter-functions) (`key`, `path`, `value`, `fullData`, etc.) with an **`event`** discriminant plus the change-specific fields; the second is a `control` object for [gating the commit](#async-updates--gating--hold):
```js
{
// ...standard node data (key, path, value, fullData, ...)
// describing the node BEFORE the change โ for `add`, this is the new
// node's position, with `value` unset
event, // 'edit' | 'add' | 'delete' | 'rename' | 'move'
newData, // the whole document AFTER the change
// ...plus one event-specific field:
newValue, // the new value (event: 'edit' | 'add')
newKey, // the new key (event: 'rename')
newPath, // the destination path (event: 'move')
}
```
Branch on `event` to handle each operation:
```js
onUpdate={(props) => {
switch (props.event) {
case 'edit': /* props.newValue */ break
case 'rename': /* props.newKey */ break
case 'move': /* props.newPath */ break
case 'add': /* props.newValue */ break
case 'delete': break
}
}}
```
The function can return nothing (the change proceeds as normal), or a value to accept/reject/transform/cancel the change. The return value can be one of:
- `true` / `void` / `undefined`: the change proceeds as normal
- `false`: treats the change as an error โ the data is not updated (reverts to the previous value) and a generic error message is displayed in the UI
- `null`: **silently cancels** the change โ no update, and *no* error message (unlike `false`). Use this to quietly abort a change that isn't an error
- `{ value: }`: replace the **edited node's** value with `` (applied at its path). Use this to tidy what the user just entered โ lower-case a string, round a number, trim, sort *this* array. Honoured for `edit` and `add`; ignored for `rename` / `move` / `delete` (those events have no node value to set)
- `{ data: }`: replace the **whole document** with ``. Use this for cross-field changes โ stamping a `lastModified`, sorting sibling nodes, canonicalising the structure. Works for every event. (Returning both `value` and `data` is a mistake: `data` wins and `value` is ignored, with a console warning.)
- `{ error: }` (or `{ error: { code, message } }`): treats the change as an error, with your provided message shown in the UI
(Any of the above may also be returned from an `async` function / `Promise`.)
[](https://carlosnz.github.io/json-edit-react/examples/on-update)
### Async updates & gating โ `hold()`
Whether a commit is **optimistic** depends on your `onUpdate`. A **synchronous** `onUpdate` โ the typical case for local or [JSON-Schema](#json-schema-validation) validation โ is resolved *in place*: a valid edit commits, and a rejected one (`false`, `{ error }`, or a thrown error) is simply never applied, so the input reverts and the error shows with no transient write to your `data`. An **asynchronous** `onUpdate` (e.g. a network save) can't be known in time, so the commit is **optimistic**: the input closes and the data updates immediately, then `onUpdate` runs in the background and a rejection (including a rejected promise) is automatically reverted and the error surfaced. A slow `onUpdate` therefore never blocks the editor, and the user can keep working. Each in-flight commit is tracked independently, so a late failure reverts only its own node and can't clobber a newer edit.
Structural changes โ **delete**, drag-and-drop **move**, and adding an **array** item โ have no open input to keep responsive, so an *asynchronous* `onUpdate` waits a brief moment (~100ms) before applying optimistically: a result that arrives inside that window settles *in place* (the node is never removed/relocated, so a rejected delete keeps the node and shows its error immediately), and only a slower one falls back to apply-then-revert. A rejected **move** has no settled position to anchor an inline message to, so it reports through the [`onEditEvent`](#listening-to-the-lifecycle--oneditevent) `updateError` event rather than an inline error.
If instead you want to **hold the editor open** until a decision resolves โ e.g. to show a confirmation dialog, or to validate before the value is committed โ call `hold()` on the second argument:
```js
onUpdate={async (props, { hold }) => {
const release = hold() // editor stays open; the rest of the tree is blocked
const ok = await myConfirmDialog(props)
if (!ok) return null // abort โ the edit is discarded
release() // commit now (closes the editor)
}}
```
- `hold()` **must be called synchronously**, before the first `await`.
- While held, the editor stays open and the rest of the tree can't be edited (one operation at a time).
- `release()` applies the change and closes the editor.
- If you `hold()` but never `release()`, the eventual `onUpdate` result decides โ the change commits when the promise resolves (unless it resolves to a reject/cancel). So a plain `hold()` โ `await` โ `return` keeps the editor open for the duration and then commits.
> [!TIP]
> A common difficulty in React is getting a modal confirmation to `await` a decision. Modals are fundamentally *declarative* โ you render `` and respond to its button callbacks โ but an async `onUpdate` wants to ask *imperatively* ("did the user confirm?") and carry on with the answer. Bridging the two by hand means juggling a deferred promise, the dialog's open state, and core's synchronous `hold()` gate all at once.
>
> [`@json-edit-react/utils`](https://www.npmjs.com/package/@json-edit-react/utils) does that bridging for you. **`useConfirmOnUpdate`** lets you declare *when* to confirm and *what* to say, and returns a ready-made `onUpdate` plus the `dialog` state to drive your own modal; the lower-level **`useJsonEditorConfirm`** hands back an awaitable `confirm()` (`Promise`) for gating anything โ an editor edit, a toolbar action, a custom-node button. You still bring the modal; the hook owns the `await`.
[](https://carlosnz.github.io/json-edit-react/examples/confirm-and-settle)
### `onChange` โ validating each keystroke
Similar to the Update function, the **`onChange`** function can be used to validate user input, except it's executed as the user types, not on submission. You can use this to restrict, constrain or transform user input โ e.g. limiting numbers to positive values, or preventing line breaks in strings. The function *must* return a value in order to update the user input field, so if no changes are to be made, just return the input value unmodified.
The input is the standard [node data](#filter-functions) (`key`, `path`, `value`, `fullData`, etc.) with the in-progress `newValue` included in the object. (Since this runs *before* the data is committed, there's no `newData` โ `value` is the current value, `fullData` the current document.)
[](https://carlosnz.github.io/json-edit-react/examples/on-change)
### `onError`
Normally, the component will display simple error messages whenever an error condition is detected (e.g. invalid JSON input, duplicate keys, or custom errors returned by the [`onUpdate` function](#onupdate--accept-reject-transform)). However, you can provide your own `onError` callback to capture the error data in order to implement your own error UI, or run additional side effects. (In the former case, you'd probably want to disable the `showErrorMessages` prop, too.) It receives the standard [node data](#filter-functions) (`key`, `path`, `value`, `fullData`, etc.) with the following additional fields spread on top:
```js
{
// ...standard node data (key, path, value, fullData, ...)
errorValue, // the erroneous value that failed to update the property
error: { // a JerError
code, // one of 'UPDATE_ERROR' | 'DELETE_ERROR' | 'ADD_ERROR'
// | 'RENAME_ERROR' | 'MOVE_ERROR' | 'INVALID_JSON' | 'KEY_EXISTS'
message // the (localised) error message that would be displayed
}
}
```
[](https://carlosnz.github.io/json-edit-react/examples/custom-error-ui)
### `onCopy`
The `onCopy` callback runs whenever an item is **copied** to the clipboard. It receives the standard [node data](#filter-functions) (`key`, `path`, `value`, `fullData`, etc.) with the following additional fields spread on top:
```js
{
// ...standard node data (key, path, value, ...)
type // Either "path" or "value" depending on whether "Cmd/Ctrl" was pressed
stringValue // A nicely stringified version of the copied value
// (i.e. what the clipboard actually receives)
success // true/false -- whether the clipboard copy action actually succeeded
error // a JerError `{ code: 'CLIPBOARD_ERROR', message }`
// present only when `success === false`
}
```
> [!TIP]
> Since there is very little user feedback when clicking "Copy", a good idea would be to present some kind of notification (see [Demo](https://carlosnz.github.io/json-edit-react/) "Toast" notifications). There are situations (such as an insecure environment) where the browser won't actually permit any clipboard actions. In this case, the `success` property will be `false`, so you can handle it appropriately.
### JSON Schema validation
It's possible to do full [JSON Schema](https://json-schema.org/) validation by creating an [`onUpdate`](#onupdate--accept-reject-transform) that passes the data to a 3rd-party schema validation library (e.g. [Ajv](https://ajv.js.org/)). This will then reject any invalid input, and display an error in the UI (or via a custom [onError](#onerror) function). You can see an example of this in the [Demo](https://carlosnz.github.io/json-edit-react/?data=jsonSchemaValidation) with the "JSON Schema Validation" data set (and the "Custom Nodes" data set).
[](https://carlosnz.github.io/json-edit-react/examples/json-schema-validation)
## Appearance & theming
### Using a prebuilt theme (`@json-edit-react/themes`)
A selection of curated themes is available in the [`@json-edit-react/themes`](#optional-companion-packages) companion package (as seen in the [Demo app](https://carlosnz.github.io/json-edit-react/)). Install the package, then import a theme and pass it as the `theme` prop:
```sh
npm i @json-edit-react/themes
```
```js
import { JsonEditor } from 'json-edit-react'
import { githubDarkTheme } from '@json-edit-react/themes'
const MyApp = () => {
const [ data, setData ] = useState({ one: 1, two: 2 })
return
}
```
> [!TIP]
> If you've created a cool theme, feel free to [submit a PR](https://github.com/CarlosNZ/json-edit-react/pulls) to include it in the themes package
### Customising styles โ the `theme` object
However, you can pass in your own theme object, or part thereof. A theme object looks like the following (this is the "default" theme definition):
```js
{
displayName: 'Default',
icons: { โฆ }, // optional per-glyph IconDefinitions โ see "Icons" below
styles: {
container: {
backgroundColor: '#f6f6f6',
fontFamily: 'monospace',
},
// collection: {},
// collectionInner: {},
// collectionElement: {},
// headerRow: {},
// valueRow: {},
// dropZone: {},
property: '#292929',
bracket: { color: '#002b36', fontWeight: 'bold' },
itemCount: { color: '#0000004d', fontStyle: 'italic' },
string: '#cb4b16',
number: '#268bd2',
boolean: 'green',
null: { color: '#dc322f', fontVariant: 'small-caps', fontWeight: 'bold' },
input: ['#292929'],
inputHighlight: '#b3d8ff',
error: { fontSize: '0.8em', color: 'red', fontWeight: 'bold' },
iconCollection: '#002b36',
iconEdit: '#2aa198',
iconDelete: '#cb4b16',
iconAdd: '#2aa198',
iconCopy: '#268bd2',
iconOk: 'green',
iconCancel: '#cb4b16',
},
}
```
The `styles` property is the main one to focus on. Each key (`property`, `bracket`, `itemCount`) refers to a part of the UI. The value for each key is *either*:
- a `string`, in which case it is interpreted as the colour (or background colour in the case of `container` and `inputHighlight`)
- a full CSS style object for fine-grained definition. You only need to provide properties you wish to override โ all unspecified ones will fallback to either the default theme, or another theme that you specify as the "base".
- a `Style Function`, which is a variant of [Filter Function](#filter-functions) tha takes the same input, but returns a CSS style object (or `null`). This allows you to *dynamically* change styling of various elements based on content or structure. (An example is in the [Demo](https://carlosnz.github.io/json-edit-react/?data=customNodes) "Custom Nodes" data set, where the character names are styled larger than other string values)
- an array combining any of the above. Static styles merge left โ right (later wins per property); a "Style Function" always applies *last*, on top of the merged statics, and multiple functions compose in order. So you can pair static "fallback" styles with a conditional function โ when the function returns `null` it contributes nothing, leaving the statics showing through.
`inputHighlight` is the one exception to the above: it sets the text-selection colour through a `::selection` rule (surfaced as a single CSS custom property), so it accepts **only a colour string** โ not a style object, function, or array.
For a simple example, you can take an existing theme and override just a few things โ pair static overrides (a fixed icon colour, bold-italic booleans) with a conditional style function, all pinned in place as you switch the base theme:
[](https://carlosnz.github.io/json-edit-react/examples/theme-overrides)
Here's another cool use for Style Functions:
[](https://carlosnz.github.io/json-edit-react/examples/heat-map)
So, to summarise, the `theme` prop can take *either*:
- an imported theme, e.g `"candyWrapperTheme"`
- a theme object:
- can be structured as above with `fragments`, `styles`, `displayName`, `icons` (glyphs โ see [Icons](#icons)) etc., or just the `styles` part (at the root level)
- any number of theme objects (each can be as full or minimal as you like) in an array (with later ones taking precedence when they overlap properties)
You can play round with live editing of the themes in the [Demo app](https://carlosnz.github.io/json-edit-react/?data=editTheme) with the "Edit this theme!" data set.
> [!NOTE]
> #### Sizing and scaling
> Internally, all sizing and spacing is done in `em`s, never `px` (aside from the [`baseFontSize`](#look-and-feel--ui), which sets the "base" size). This makes scaling a lot easier โ just change the `baseFontSize` prop (or set `fontSize` on the main container via targeting the class, or tweaking the [theme](#customising-styles--the-theme-object)), and watch the *whole* component scale accordingly.
### CSS classes
Another way to style the component is to target the CSS classes directly. Every element in the component has a unique class name, so you should be able to locate them in your browser inspector and override them accordingly. All class names begin with the prefix `jer-`, e.g. `jer-collection-header-row`, `jer-value-string`.
Note that theme styles are applied *inline*, so any property the theme sets takes precedence over your own CSS rules (short of `!important`). CSS-class overrides are therefore best for structural/layout tweaks the theme doesn't touch (spacing, sizing, borders); colours and fonts are best set through the `theme` prop.
### Style fragments
A `fragments` object is a convenience to define named, reusable style tokens โ a colour or a snippet of CSS โ and reference them by name from any element's value. Think of it as a palette: define a value once and reuse it in several unrelated places, so a later tweak only happens in one spot.
```js
fragments: { accent: '#E63946' },
styles: {
property: 'accent',
iconEdit: 'accent',
}
```
A fragment can also be a full style object, and can be mixed with extra properties (and other fragments) in an array:
```js
fragments: { iconAdjust: { fontSize: '110%', marginRight: '0.6em' } },
styles: {
iconEdit: ['iconAdjust', { marginLeft: '1em' }],
}
```
### Icons
A theme owns its icon **glyphs** as well as their colour, though any icons not defined fall through as per the styles, bottoming out with the default icons.
The `icons` property is for defining the glyphs; the `styles.icon...` properties control the CSS that gets applied to them, though if an icon as specific colours applied to an inner path, these won't be overridden. The property is structure as follows:
```ts
interface ThemeIcons {
add?: IconDefinition
edit?: IconDefinition
delete?: IconDefinition
copy?: IconDefinition
ok?: IconDefinition
cancel?: IconDefinition
collection?: IconDefinition
}
interface IconDefinition {
content: React.ReactNode // the inner SVG markup โ //โฆ (no outer
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/)
[](https://deepwiki.com/CarlosNZ/json-edit-react)
[](https://github.com/CarlosNZ/json-edit-react/discussions)
[](https://github.com/sponsors/CarlosNZ)
### 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](#appearance--theming), CSS overrides or targeted classes
- ๐ฆ **Self-contained** โ plain HTML/CSS, no external UI library dependencies, and *zero runtime dependencies*
- ๐ **Search & filter** โ find data by key, value or custom function
- ๐ง **[Custom components](#custom-nodes--components)** โ replace keys and/or values with specialised components (e.g. date picker, links, images, `undefined`, `BigInt`, `Symbol`)
- ๐ **[Localisation](#localisation)** โ easily translate UI labels and messages
- ๐ **[Drag-n-drop](#drag-and-drop-reordering)** re-ordering within objects/arrays
- ๐น **[Keyboard customisation](#keyboard-control)** โ define your own key bindings
- ๐ฎ **[External control](#programmatic-control)** via callbacks and imperative methods
๐ก Try the **[Live Demo](https://carlosnz.github.io/json-edit-react/)** to see these features in action!
> [!IMPORTANT]
> This documentation is for V2 of **json-edit-react**. Looking for V1? See the [V1 docs](https://github.com/CarlosNZ/json-edit-react/tree/v1.x#readme) and [V1 demo](https://carlosnz.github.io/json-edit-react-v1/).
>
> If you're upgrading from V1, be sure to read the [migration guide](https://github.com/CarlosNZ/json-edit-react/blob/main/migration-guide.md).
>
> ๐ค๏ธ Got feedback? [Open an issue](https://github.com/CarlosNZ/json-edit-react/issues), or join the conversation in [Discussions](https://github.com/CarlosNZ/json-edit-react/discussions/categories/announcements).
## Optional Companion Packages
- **THEMES**: [@json-edit-react/themes](https://www.npmjs.com/package/@json-edit-react/themes) โ curated, ready-made [themes](#using-a-prebuilt-theme-json-edit-reactthemes)
- **COMPONENTS**: [@json-edit-react/components](https://www.npmjs.com/package/@json-edit-react/components) - custom node components (links, date picker, etc.)
- **UTILITIES**: [@json-edit-react/utils](https://www.npmjs.com/package/@json-edit-react/utils) โย a collection of helpers and tools for extending and streamlining your **json-edit-react** experience
----
## Contents
- [Using the editor (for end users)](#using-the-editor-for-end-users)
- [Installation](#installation)
- [Implementation](#implementation)
- [Props Reference](#props-reference)
- [Managing state](#managing-state)
- [Filter Functions](#filter-functions)
- [Controlling editing](#controlling-editing)
- [Reacting to changes](#reacting-to-changes)
- [Appearance \& theming](#appearance--theming)
- [Initial expansion โ `collapse`](#initial-expansion--collapse)
- [Search \& filtering](#search--filtering)
- [Localisation](#localisation)
- [Keyboard control](#keyboard-control)
- [Custom Nodes \& Components](#custom-nodes--components)
- [Overriding and extending the UI](#overriding-and-extending-the-ui)
- [Programmatic control](#programmatic-control)
- [Performance considerations](#performance-considerations)
- [Undo functionality](#undo-functionality)
- [Exported helpers \& types](#exported-helpers--types)
- [Issues \& support](#issues--support)
- [Inspiration](#inspiration)
- [Changelog](#changelog)
## Using the editor (for end users)
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-Enter or 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
- Use Tab/Shift-Tab to quickly move from one value to another when 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, the โ / โ arrow keys will increment/decrement the value
- For Boolean inputs, the 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!
## Installation
```sh
# Depending on your package manager:
npm i json-edit-react
# OR
yarn add json-edit-react
# OR
pnpm add json-edit-react
```
## Implementation
```jsx
import { JsonEditor } from 'json-edit-react'
// In your React component:
return (
To define an Enum, just add an object with the following structure to your "Types" array (either directly in the prop, or returned from the callback):
```js
{
enum: "My Enum Type" // name that will appear in the Types selector drop-down
values: [ // the list of allowed values
"Option A",
"Option B",
"Option C"
]
matchPriority: 1 // (Optional) used to recognize existing string values
// as the particular type (see below)
}
```
What is `matchPriority`? Well, when the data object is initialised, we have no way to know whether a given string value is "just a string" or is supposed to be one of the members of an Enum type (and we don't want to assume that if it's listed somewhere in an Enum `values` list that it definitely *should* be restricted to that type). So, if `matchPriority` is not defined, then that Enum type will *never* be initially assigned to a potentially matching Enum value when editing. If `matchPriority` is defined, then the highest priority Enum that has the value in its `values` list will be assigned (so if multiple Enums have overlapping `values`, the one with the highest priority will be applied.).
If the type of a given node is going to be *restricted* to a particular Enum type (i.e. the `allowTypeSelection` prop returns *only* one value), then a `matchPriority` is essential, otherwise it wouldn't be possible to switch a `string` to that type.
You can see examples of this in the [Star Wars data set](https://carlosnz.github.io/json-edit-react/?data=starWars) of the Demo โ the `eye_color`, `skin_color`, `hair_color` and `films` values are all restricted to a single, matching Enum type.
> [!NOTE]
> When editing, once an Enum type is selected from the Types selector, that node will continue to be displayed as that type for subsequent edits in the same session -- the `matchPriority` is purely for automatic recognition of a given value as a specific type when *first* editing it.
[](https://carlosnz.github.io/json-edit-react/examples/enums)
### New-key restrictions & default values
You can restrict the available properties a given collection node can have (when adding new properties) by setting the `newKeyOptions` prop. The value can be either a **list of keys**, or a [`NewKeyOptionsFunction`](#filter-functions) callback which returns the key list.
This will cause the UI to present a Drop-down selector when adding a new key rather than the usual text input:
The initial *value* for newly-added keys can also be defined with the `defaultValue` prop -- this can be *any* value, or a [`DefaultValueFunction`](#filter-functions) callback returning any value. The input signature is almost the same as standard `FilterFunctions`, but it can take a second argument, which is the name of the new key.
You can see an example of this in the [JSON Schema validation data](https://carlosnz.github.io/json-edit-react/?data=jsonSchemaValidation) of the Demo app when you add new keys to either the `address` collection or the root node.
[](https://carlosnz.github.io/json-edit-react/examples/new-key-restrictions)
### Drag-and-drop reordering
The `allowDrag` property controls which items (if any) can be dragged into new positions. By default, this is *off*, so you must set `allowDrag = true` to enable this functionality. Like the Edit permissions above, this property can also take a `FilterFunction` for fine-grained control. There are a couple of additional considerations, though:
- JavaScript does *not* guarantee object property order, so enabling this feature may yield unpredictable results. See [here](https://dev.to/frehner/the-order-of-js-object-keys-458d) for an explanation of how key ordering is handled.
> [!WARNING]
> It is strongly advised that you only enable drag-and-drop functionality if:
> 1. you're sure object keys will always be simple strings (i.e. not digits or non-standard characters)
> 2. you're saving the data in a serialisation format that preserves key order. For example, storing in a Postgres database using the `jsonb` (binary JSON) type, key order is meaningless, so the next time the object is loaded, the keys will be listed alphabetically.
- The `allowDrag` filter applies to the *source* node (the one being dragged) โ it controls whether a node can be **picked up** at all.
- What a drop is allowed to do then depends on where it lands, and reuses your existing permission filters โ so if you've configured restrictive editing constraints with Filter functions, they can't be circumvented via drag-n-drop:
| Drop | Is aโฆ | Requires |
| --- | --- | --- |
| Within the same collection | **reorder** | `allowEdit` on that collection |
| Into a *different* collection | **relocate** | `allowDelete` on the source **and** `allowAdd` on the destination collection |
A relocate is a delete-then-add across collections, so it needs both halves; a reorder changes nothing's membership, so it needs neither โ only that the collection itself is editable.