--- url: https://v3-jsoneditor.netlify.app/guide/introduction.md description: >- What v3-jsoneditor is, its key features, and when to use it in a Vue 3 application. --- # Introduction **v3-jsoneditor** is a Vue 3 component that wraps [jsoneditor](https://github.com/josdejong/jsoneditor) by Jos de Jong, the battle-tested web tool for viewing, editing, formatting and validating JSON. It gives you a single `` component with `v-model` support, a modern theme, a fullscreen mode and a typed API, so you can drop a full JSON editor into any Vue 3 app in a couple of lines. ```vue ``` ## Features * **Two-way binding** with `v-model` for any JSON value: objects, arrays, strings, numbers, booleans and `null`. * **Five editing modes** from jsoneditor: `tree`, `code`, `form`, `text` and `view`, with a configurable mode switcher and `v-model:currentMode`. * **JSON Schema validation** through `options.schema`, plus custom validation via `options.onValidate` and a `validation-error` event. * **Themes**: a modern `light` theme (default), `dark`, `auto` (follows your site's dark mode) and `classic` (the original jsoneditor look), all customizable with CSS variables. * **Fullscreen mode** in every editor mode, controllable with `v-model:fullscreen`, closable with Esc. * **Custom toolbar** content through the `#toolbar` slot. * **Full jsoneditor access**: pass any [jsoneditor option](https://github.com/josdejong/jsoneditor/blob/master/docs/api.md#configuration-options) through `options`, or grab the raw instance with `getEditor()`. * **SSR-safe**: jsoneditor is loaded lazily on the client, so the component can be imported in Nuxt and VitePress. * **TypeScript types** with JSDoc ship with the package. * **Internationalization**: `en`, `zh-CN`, `pt-BR`, `tr`, `ja`, `fr-FR`, `de`, `ru` and `es`. ## When to use it v3-jsoneditor is a good fit when you need to: * Let users edit configuration, settings or API payloads as structured JSON. * Inspect API responses or logs in an admin panel or developer tool. * Offer a read-only, collapsible JSON viewer. * Validate user-supplied JSON against a JSON Schema before saving it. If you only need to *display* a small, static snippet of JSON, a `
` block with syntax highlighting is lighter. For everything interactive, read on.

## Next steps

* [Getting Started](/guide/getting-started): install and render your first editor.
* [Usage](/guide/usage): `v-model`, modes, options, methods and events.
* [Examples](/examples/): live demos you can copy.
* [Playground](/playground): try every prop interactively.

---

---
url: https://v3-jsoneditor.netlify.app/guide/getting-started.md
description: >-
  Install v3-jsoneditor, register it locally or globally, use it from a CDN, and
  render a minimal JSON editor.
---

# Getting Started

## Installation

::: code-group

```bash [npm]
npm install v3-jsoneditor
```

```bash [pnpm]
pnpm add v3-jsoneditor
```

```bash [yarn]
yarn add v3-jsoneditor
```

```bash [bun]
bun add v3-jsoneditor
```

:::

`vue` (version 3) is a peer dependency. `jsoneditor` is installed automatically as a dependency, and its stylesheet is imported by the component, so there is nothing else to set up.

## Local import

Import the component where you need it. This is the recommended approach because it keeps your bundle tree-shakable.

```vue



```

## Global registration

The default export carries an `install` function, so you can register it as a plugin. This registers the component as `Vue3Jsoneditor`, usable as `` or ``.

```js
// main.js
import { createApp } from 'vue'
import Vue3Jsoneditor from 'v3-jsoneditor'
import App from './App.vue'

const app = createApp(App)
app.use(Vue3Jsoneditor)
app.mount('#app')
```

### Global defaults

Pass a config object as the second argument to set defaults for every editor in your app. Every key except `componentName` is a default for the prop of the same name; `options` is merged with each component's own `options` (the component wins).

```js
app.use(Vue3Jsoneditor, {
  componentName: 'JsonEditor', // default: 'Vue3Jsoneditor'
  theme: 'auto',
  height: 500,
  debounce: 200,
  options: { search: false },
})
```

The named `install` export works too, as does registering the component yourself under any name:

```js
import Vue3Jsoneditor, { install } from 'v3-jsoneditor'

app.use({ install })
// or
app.component('JsonEditor', Vue3Jsoneditor)
```

## CDN / UMD

Without a build step, load the stylesheet, Vue, jsoneditor and then the UMD bundle. The bundle exposes a global `Vue3Jsoneditor` and uses jsoneditor from its `JSONEditor` global. `v3-jsoneditor/dist/style.css` already contains jsoneditor's own CSS, so you only need one stylesheet.

```html


  
    
  
  
    
{{ json }}
``` ::: tip In in-DOM templates (HTML written directly in the page), use the kebab-case tag ``, because the browser lowercases tag names before Vue sees them. ::: ## Minimal example A complete component that edits a JSON object and shows the bound value: ```vue ``` See the [Basic example](/examples/basic) for a live version. ## Nuxt The component is SSR-safe to import, and the editor renders on the client. See [SSR, Nuxt & VitePress](/guide/ssr) for a Nuxt plugin and recommended `` usage. ## Next steps * [Usage](/guide/usage): modes, options, methods and events. * [Theming](/guide/theming): pick a theme or brand it with CSS variables. * [Props reference](/api/props). --- --- url: https://v3-jsoneditor.netlify.app/guide/usage.md description: >- Bind JSON with v-model, switch editor modes, pass jsoneditor options, call methods through a template ref, and listen to events. --- # Usage ## v-model `v-model` binds any JSON value: an object, array, string, number, boolean or `null`. ```vue ``` How updates flow: * **Editor to parent**: every valid edit emits `update:modelValue` and `change` with the parsed value. * **Parent to editor**: assigning a new value updates the editor in place using jsoneditor's `update()` (the editor is not re-created). In `tree`, `view` and `form` modes the tree is expanded automatically after each update. * **Invalid text**: while the text in `code` or `text` mode is not valid JSON, the model is not updated and an `error` event is emitted instead. * **Clearing**: emptying the editor in `code` or `text` mode emits `null`. ### Raw text with v-model:text `v-model:text` binds the raw editor text, including invalid JSON while the user is typing. This is useful to preserve the user's formatting or to save drafts. If `text` is provided initially, it wins over `modelValue`. ```vue ``` ### Debouncing updates By default every keystroke emits `update:modelValue`, `update:text` and `change`. Set `debounce` (milliseconds) to batch them; 150 to 300 is recommended for large documents. ```vue ``` ::: tip For big documents, prefer `shallowRef` over `ref` so Vue does not make every nested node deeply reactive. See [Large JSON](/examples/large-json). ::: ## Modes jsoneditor offers five modes: | Mode | Description | | --- | --- | | `tree` | Collapsible tree with inline editing, drag and drop, search and undo. | | `code` | Ace-powered code editor with syntax highlighting and formatting. **Default.** | | `form` | Like `tree`, but only values are editable; the structure is locked. | | `text` | Plain textarea with format/compact/repair buttons. | | `view` | Read-only tree. | Set the initial mode with `current-mode` and limit the mode switcher with `mode-list`: ```vue ``` Use `v-model:currentMode` to keep the active mode in sync when the user switches through the menu, or to switch it from outside: ```vue ``` The `mode-change` event fires with `(newMode, oldMode)` whenever the mode changes. ::: warning Changing `modeList` or `language` after mount re-creates the editor. The content is preserved, but transient state such as undo history is lost. ::: ## Read-only `read-only` makes the editor read-only in every mode, while keeping mode switching, search and copying available: ```vue ``` For a read-only tree only, `current-mode="view"` also works. See the [Read-only example](/examples/read-only). ## Layout props | Prop | Default | Description | | --- | --- | --- | | `main-menu-bar` | `true` | Show the main menu bar. | | `navigation-bar` | `true` | Show the breadcrumb navigation bar (`tree`, `view`, `form`). | | `status-bar` | `true` | Show the status bar (`code`, `text`). | | `indentation` | `2` | Spaces used when formatting JSON. | ```vue ``` ## Passing jsoneditor options The `options` prop is passed straight to the jsoneditor constructor, so any [jsoneditor configuration option](https://github.com/josdejong/jsoneditor/blob/master/docs/api.md#configuration-options) works: ```vue ``` ### Precedence When the same setting can come from several places, the component resolves it in this order: 1. **Component props** such as `currentMode`, `modeList`, `language`, `indentation`, `mainMenuBar`, `navigationBar` and `statusBar` win. 2. **`options`** values come next (the component's `options` merged over any global `options` from `app.use`). 3. **Defaults** of the component (for example `indentation: 2`) apply last. For example, the starting mode is `currentMode` if set, otherwise `options.mode`, otherwise `'code'`. ### Your callbacks are merged The component uses several jsoneditor callbacks internally (`onChange`, `onModeChange`, `onFocus` and so on). If you pass your own, such as `options.onChange`, **both run**: the component's handler (which emits events) and yours. ```js const options = { onChange() { console.log('changed (from options.onChange)') }, } ``` The one exception is `onColorPicker`: jsoneditor's built-in color picker is used unless you listen to `@colorPicker` or pass `options.onColorPicker`. In most cases the component's events are more convenient than raw callbacks; use whichever you prefer. ## Template ref and methods Grab the component with a template ref to call its exposed methods: ```vue ``` | Method | Description | | --- | --- | | `getEditor()` | The raw `JSONEditor` instance, or `null` before mount. | | `get()` | The current parsed JSON; throws if the text is invalid. | | `getText()` | The raw editor text. | | `validate()` | Runs validation; resolves with an array of errors. | | `expandAll()` | Expand all nodes (`tree`, `view`, `form`). | | `collapseAll()` | Collapse all nodes (`tree`, `view`, `form`). | | `setEditorContent(json)` | Replace the editor content. | | `toggleFullScreen()` | Enter or exit fullscreen. | | `focus()` | Focus the editor. | See the [Methods reference](/api/methods) for details. ## Events ```vue ``` The full list, with payloads, is in the [Events reference](/api/events). ## Language Set the UI language with `language`. Supported values: `en` (default), `zh-CN`, `pt-BR`, `tr`, `ja`, `fr-FR`, `de`, `ru`, `es`. ```vue ``` ## Height `height` accepts a CSS length string or a number (pixels): ```vue ``` Without `height`, the editor is `400px` tall. That default has zero specificity, so a height you set with your own CSS class always wins. --- --- url: https://v3-jsoneditor.netlify.app/guide/validation.md description: >- Validate JSON with a JSON Schema via options.schema, add custom validation with onValidate, and react to validation-error and parse error events. --- # Validation jsoneditor has built-in validation powered by [Ajv](https://ajv.js.org/). v3-jsoneditor exposes it through `options` and adds events so your app can react to problems. ## JSON Schema Pass a [JSON Schema](https://json-schema.org/) as `options.schema`. Invalid values are highlighted in the editor and listed at the bottom. ```vue ``` Use `options.schemaRefs` to provide referenced sub-schemas (`$ref`). ### Reactive schema The schema is reactive: when `options.schema` changes, the component calls jsoneditor's `setSchema()` without re-creating the editor. ```vue ``` ## Custom validation For rules that JSON Schema cannot express, use jsoneditor's `onValidate`. It receives the JSON and returns an array of errors (or a Promise of one). Each error has a `path` and a `message`. ```js const options = { onValidate(json) { const errors = [] if (json?.team && !json.team.includes(json.owner)) { errors.push({ path: ['owner'], message: 'Owner must be a team member' }) } return errors }, } ``` `onValidate` runs in addition to `schema` validation. ## Reacting to errors ### `validation-error` Emitted with the array of validation errors (schema and custom) whenever validation runs. An empty array means the document is valid. ```vue ``` ### `error` Emitted when the text in `code` or `text` mode is not valid JSON (a parse error). The model keeps its last valid value until the text parses again. ```vue ``` ::: tip Use `error` for "the text is not JSON at all" and `validation-error` for "the JSON is well-formed but breaks the rules". ::: See the [JSON Schema example](/examples/json-schema) for a live demo. --- --- url: https://v3-jsoneditor.netlify.app/guide/theming.md description: >- Choose between the light, dark, auto and classic themes, customize colors with CSS variables, and scope overrides per editor. --- # Theming v3-jsoneditor ships a modern look on top of jsoneditor, with matching styling for the menu bar, tree, Ace code editor and modals. ## The `theme` prop | Value | Description | | --- | --- | | `light` | Modern light theme. **Default.** | | `dark` | Modern dark theme, including dark styling for the Ace code editor. | | `auto` | Follows the page: dark when an ancestor `html` element has the `dark` class (VitePress, Nuxt Color Mode, Tailwind `darkMode: 'class'`), otherwise follows the operating system's `prefers-color-scheme`. | | `classic` | The original jsoneditor look (blue menu bar), as in v3-jsoneditor 0.0.x. | ```vue ``` Theme gallery summary: `light` uses a white background, light gray surfaces and an indigo accent. `dark` uses a near-black background, dark gray surfaces, light text and dark styling for the Ace code editor. `auto` switches between `light` and `dark` based on the `html.dark` class or `prefers-color-scheme`. `classic` keeps jsoneditor's original styling with its blue (`#3883fa`) menu bar and default Ace theme. ## CSS variables The modern themes (`light`, `dark`, `auto`) are driven by CSS custom properties on the `.v3-jsoneditor` root element. Override any of them to match your brand. | Variable | Purpose | | --- | --- | | `--vje-accent` | Accent color: menu highlights, active mode, focus rings, selection. | | `--vje-bg` | Editor background. | | `--vje-surface` | Menu bar, navigation bar and status bar background. | | `--vje-border` | Border and divider color. | | `--vje-text` | Main text color. | | `--vje-muted` | Secondary text: field names, line numbers, placeholders. | | `--vje-radius` | Corner radius of the editor and its controls. | | `--vje-font-mono` | Monospace font used in tree, code and text modes. | | `--vje-shadow` | Shadow of the editor container, menus and modals. | | `--vje-z-fullscreen` | `z-index` of the editor in fullscreen mode. | ### Global overrides Apply to every editor on the page: ```css .v3-jsoneditor { --vje-accent: #10b981; --vje-radius: 12px; --vje-font-mono: 'JetBrains Mono', ui-monospace, monospace; } ``` ### Scoped overrides Add a class to a single editor and override variables only there: ```vue ``` Classes set on the component are applied to its root element, the same element that carries `.v3-jsoneditor`. Combine both classes (`.brand-editor.v3-jsoneditor`) so your values win over the built-in theme regardless of stylesheet order, with no `!important` needed. ::: tip For a dark variant of a custom palette, scope your values under the dark theme too, for example `html.dark .brand-editor { ... }` when you use `theme="auto"`. ::: See the [Custom theme example](/examples/custom-theme) for a live demo. ## Dark Ace editor In `code` mode, jsoneditor uses the Ace editor. The modern themes restyle jsoneditor's default Ace theme with the same CSS variables (gutter, active line, selection, cursor and JSON token colors), so `dark` and `auto` give you a dark code editor without loading anything extra. To use a different Ace theme, set `options.theme` (for example `options: { theme: 'ace/theme/monokai' }`) and load that theme yourself. The component's color overrides only apply to the default theme. ## Toolbar icons The modern themes replace jsoneditor's sprite icons in the menu bar with crisp [Solar](https://icon-sets.iconify.design/solar/) icons that pick up `--vje-text` and `--vje-accent`. The `classic` theme keeps jsoneditor's original sprite. ## CSS delivery and CSP In the ESM build, the theme CSS is injected automatically by JavaScript, so there is nothing to import. For CDN or strict Content Security Policy setups, `dist/style.css` is also published and can be linked as a regular stylesheet. ## Going further Need more than variables? All jsoneditor class names (`.jsoneditor`, `.jsoneditor-menu`, `.jsoneditor-tree`, ...) are still present, so you can target them with regular CSS scoped under your own class. --- --- url: https://v3-jsoneditor.netlify.app/guide/fullscreen.md description: >- Show the fullscreen button, control fullscreen with v-model:fullscreen, listen for fullscreen-change, and adjust its z-index. --- # Fullscreen The editor can expand to fill the whole viewport, which is handy for large documents. ## The fullscreen button The `plus` prop (default `true`) shows a fullscreen button in the menu bar, in **every** mode. Hide it with: ```vue ``` ## v-model:fullscreen Bind `fullscreen` to read or control the state from your component: ```vue ``` The state stays in sync whether fullscreen is toggled by the button, by Esc, by the prop or by a method call. ## Events `fullscreen-change` is emitted with a boolean whenever the state changes (alongside `update:fullscreen`): ```vue ``` ## Programmatic toggle ```vue ``` ## Behavior * Press Esc to exit fullscreen. * While fullscreen, page scrolling is locked (`overflow: hidden` on `body`) and restored on exit or unmount. * The editor is fixed over the viewport with `z-index: var(--vje-z-fullscreen)`. If your app has headers or dialogs with a higher `z-index`, raise it: ```css .v3-jsoneditor { --vje-z-fullscreen: 10000; } ``` ::: tip This is an in-page overlay, not the browser Fullscreen API, so it works inside iframes and does not require a user permission prompt. ::: --- --- url: https://v3-jsoneditor.netlify.app/guide/ssr.md description: >- Use v3-jsoneditor with server-side rendering in Nuxt 3/4 and VitePress; the editor loads jsoneditor lazily and renders on the client. --- # SSR, Nuxt & VitePress jsoneditor touches `window` and `document`, so it can only run in the browser. v3-jsoneditor handles this for you: * jsoneditor is **imported lazily inside `onMounted`**, so importing `v3-jsoneditor` during server rendering is safe. * On the server the component renders an empty container. The editor itself appears on the client after mount. Because the editor appears only after hydration, wrapping it in `` with a placeholder of the same height is recommended to avoid layout shift. You can also use the component's default slot as a placeholder: its content is rendered until the editor has mounted. ```vue
Loading editor...
``` ## Nuxt 3 / Nuxt 4 ### Plugin (global registration) ```ts // plugins/v3-jsoneditor.client.ts import Vue3Jsoneditor from 'v3-jsoneditor' export default defineNuxtPlugin((nuxtApp) => { nuxtApp.vueApp.use(Vue3Jsoneditor) }) ``` The `.client` suffix registers the plugin only in the browser, so the component must be used inside ``: ```vue ``` ::: tip If you prefer a universal plugin (`plugins/v3-jsoneditor.ts`, without `.client`), that works too, since the import is SSR-safe. `` is then optional but still recommended for a stable layout. ::: ### Local import ```vue ``` ## VitePress Register the component in your theme and use it inside `` in Markdown: ```ts // .vitepress/theme/index.ts import DefaultTheme from 'vitepress/theme' import Vue3Jsoneditor from 'v3-jsoneditor' export default { extends: DefaultTheme, enhanceApp({ app }) { app.use(Vue3Jsoneditor) }, } ``` ```md ``` `theme="auto"` follows VitePress's dark mode toggle, which sets the `dark` class on ``. ## Other SSR setups The same rules apply to any SSR framework (Vite SSR, Quasar SSR, Astro with the Vue integration): import normally, render on the client (for Astro use `client:only="vue"`), and reserve the editor's height to avoid layout shift. --- --- url: https://v3-jsoneditor.netlify.app/guide/migration.md description: >- Upgrade from v3-jsoneditor 0.0.x to 0.1.0, covering the new default theme, merged option callbacks, import path, jsoneditor v10 and new features. --- # Migration to 0.1 Version 0.1.0 modernizes v3-jsoneditor while keeping the core API (`v-model`, `options`, `currentMode`, `modeList`, `language`, `height`, `plus`) intact. Most apps upgrade without code changes. This page lists what behaves differently and what is new. ## Breaking or visible changes ### New default theme The default `theme` is now the modern `light` theme. To keep the original jsoneditor look (blue menu bar), set `theme="classic"`: ```vue ``` See [Theming](/guide/theming). ### Option callbacks are merged, not overridden Previously, a callback in `options` such as `onChange` could replace the component's internal handler (breaking `v-model`), or be replaced by it. Now **both run**: the component's handler (which emits events) and yours. If you used `options.onChange` as a workaround for missing events, you may now receive two notifications if you also listen to `@change`; keep one. ### Options are honored more consistently * The starting mode comes from the `currentMode` prop (default `'code'`). Props take precedence over `options`, which take precedence over defaults. * `options.indentation` is now respected. The default is `2`. ### Clearing the editor emits `null` Emptying the editor in `code` or `text` mode now emits `null` through `update:modelValue` instead of leaving the previous value. ### `modelValue` accepts any JSON `modelValue` is no longer restricted to objects. Arrays, strings, numbers, booleans and `null` are all valid, so Vue no longer warns about prop types for these. ### jsoneditor v10 The underlying jsoneditor is upgraded to v10. It drops Internet Explorer 11 support. If you used jsoneditor APIs through `getEditor()`, check the [jsoneditor changelog](https://github.com/josdejong/jsoneditor/blob/master/CHANGELOG.md). ### Import path The package entry is now the preferred import: ```js // Before import Vue3Jsoneditor from 'v3-jsoneditor/src/Vue3Jsoneditor.vue' // After import Vue3Jsoneditor from 'v3-jsoneditor' ``` The old path still works, so this change is optional, but the package entry is what the TypeScript types describe. ### Built-in color picker works again jsoneditor's built-in color picker now works. The component only overrides `onColorPicker` if you listen to `@colorPicker` or pass `options.onColorPicker`. ## New features * `theme` prop: `light`, `dark`, `auto`, `classic`. * `v-model:currentMode` and the `mode-change(newMode, oldMode)` event. * `v-model:fullscreen` and the `fullscreen-change` event; the fullscreen button works in every mode and Esc exits. * `validation-error` event for schema and custom validation. * Reactive `options.schema`. * `#toolbar` slot to add your own buttons to the menu bar. * `v-model:text` for the raw editor text. * `readOnly`, `debounce`, `indentation`, `mainMenuBar`, `navigationBar` and `statusBar` props. * Global defaults: `app.use(Vue3Jsoneditor, { theme: 'auto', height: 500, ... })`, including a custom `componentName`. * Default slot for placeholder content until the editor mounts. * `getEditor()`, `get()`, `getText()`, `validate()`, `collapseAll()` and `focus()` methods. * `height` accepts numbers (pixels). * TypeScript types with JSDoc. * SSR-safe import for Nuxt and VitePress. ## Upgrade checklist 1. Update the package: `npm install v3-jsoneditor@latest`. 2. Change imports to `import Vue3Jsoneditor from 'v3-jsoneditor'`. 3. Add `theme="classic"` if you want the old appearance. 4. If you passed `options.onChange` (or other callbacks) *and* listen to the matching event, remove the duplicate. 5. If your code treats an empty editor specially, handle `null` from `v-model`. --- --- url: https://v3-jsoneditor.netlify.app/api/props.md description: >- Reference of all v3-jsoneditor props (modelValue, options, currentMode, modeList, language, height, plus, fullscreen, theme) and the toolbar slot. --- # Props All props of ``. In templates, use kebab-case (`current-mode`) or camelCase (`currentMode`); both work. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `modelValue` | `object \| array \| string \| number \| boolean \| null` | `undefined` | The JSON value. Use with `v-model`. | | `options` | `object` | `{}` | Passed to the jsoneditor constructor. Accepts any [jsoneditor option](https://github.com/josdejong/jsoneditor/blob/master/docs/api.md#configuration-options). Callbacks are merged with the component's own. `options.schema` is reactive. | | `text` | `string` | `undefined` | Raw editor text. Use with `v-model:text`. May be invalid JSON while the user types. If provided initially, it wins over `modelValue`. | | `currentMode` | `'tree' \| 'code' \| 'form' \| 'text' \| 'view'` | `'code'` | Active editor mode. Supports `v-model:currentMode`. | | `modeList` | `string[]` | `['tree', 'code', 'form', 'text', 'view']` | Modes offered in the mode switcher. Changing it re-creates the editor. | | `language` | `string` | `'en'` | UI language: `en`, `zh-CN`, `pt-BR`, `tr`, `ja`, `fr-FR`, `de`, `ru`, `es`. Changing it re-creates the editor. | | `height` | `string \| number` | `undefined` | Editor height. A number is treated as pixels; a string is any CSS length (`'400px'`, `'50vh'`). Without it, the editor fills its parent. | | `plus` | `boolean` | `true` | Show the fullscreen button in the menu bar (all modes). | | `fullscreen` | `boolean` | `false` | Fullscreen state. Supports `v-model:fullscreen`. | | `readOnly` | `boolean` | `false` | Make the editor read-only in all modes (implemented with jsoneditor's `onEditable`). | | `debounce` | `number` | `0` | Debounce in milliseconds for `update:modelValue`, `update:text` and `change`. 150 to 300 is recommended for large documents. | | `mainMenuBar` | `boolean` | `true` | Show the main menu bar. | | `navigationBar` | `boolean` | `true` | Show the navigation bar (breadcrumbs) in `tree`/`view`/`form` modes. | | `statusBar` | `boolean` | `true` | Show the status bar (cursor position, size) in `code`/`text` modes. | | `indentation` | `number` | `2` | Spaces used to indent formatted JSON. Wins over `options.indentation`. | | `theme` | `'light' \| 'dark' \| 'auto' \| 'classic'` | `'light'` | Visual theme. `auto` follows the `html.dark` class or `prefers-color-scheme`; `classic` is the original jsoneditor look. | ## Option precedence When a setting can come from more than one place: **component props > `options` > component defaults**. | Setting | Source | | --- | --- | | Mode | `currentMode` prop (always set; default `'code'`). | | Available modes | `modeList` prop. | | Language | `language` prop. | | Indentation | `indentation` prop, then `options.indentation`, then `2`. | | Menu/navigation/status bars | `mainMenuBar` / `navigationBar` / `statusBar` props (default `true`), then the matching `options` keys. | | Callbacks (`onChange`, `onModeChange`, `onFocus`, ...) | Both the component's handler and yours run. | See [Usage: passing jsoneditor options](/guide/usage#passing-jsoneditor-options). ## Global defaults `app.use(Vue3Jsoneditor, config)` accepts defaults for every prop. All keys except `componentName` are defaults for the matching prop; `options` from the global config and from the component are merged (local wins). | Key | Type | Default | Description | | --- | --- | --- | --- | | `componentName` | `string` | `'Vue3Jsoneditor'` | Name the component is registered under. | | any prop name (`theme`, `height`, `debounce`, `language`, ...) | prop type | prop default | Default value for that prop. | | `options` | `object` | `{}` | Default jsoneditor options, merged with the `options` prop. | ```js app.use(Vue3Jsoneditor, { componentName: 'JsonEditor', theme: 'auto', height: 500, debounce: 200, options: { search: false }, }) ``` ## Slots ### `default` Placeholder content rendered until the editor has mounted, for example a loading message or skeleton. Useful with SSR, where the editor only appears on the client. ```vue
Loading editor...
``` ### `toolbar` Custom content rendered inside the jsoneditor menu bar, on the right side. It is re-attached automatically when the mode changes (jsoneditor rebuilds its menu bar on mode switch). | Slot prop | Type | Description | | --- | --- | --- | | `editor` | `JSONEditor \| null` | The raw jsoneditor instance. | | `mode` | `string` | The current mode. | ```vue ``` See the [Custom toolbar example](/examples/custom-toolbar). ## CSS variables Styling is controlled with `--vje-*` CSS variables on `.v3-jsoneditor` (`--vje-accent`, `--vje-bg`, `--vje-surface`, `--vje-border`, `--vje-text`, `--vje-muted`, `--vje-radius`, `--vje-font-mono`, `--vje-shadow`, `--vje-z-fullscreen`). See [Theming](/guide/theming#css-variables) for descriptions. ## Related * [Events](/api/events) * [Methods](/api/methods) --- --- url: https://v3-jsoneditor.netlify.app/api/events.md description: >- Reference of all events emitted by v3-jsoneditor, including v-model updates, change, error, validation-error, mode-change, fullscreen-change, focus and selection events. --- # Events All events emitted by ``. Listen with `@event-name` in templates. | Event | Payload | Description | | --- | --- | --- | | `update:modelValue` | `(json: any)` | The content changed and is valid JSON. Used by `v-model`. Emits `null` when the editor is cleared in `code`/`text` mode. | | `change` | `(json: any)` | Same as `update:modelValue`, as a plain event. | | `error` | `(err: Error)` | The text in `code`/`text` mode is not valid JSON. The model keeps its last valid value. | | `validation-error` | `(errors: Array)` | Validation ran (`options.schema` and/or `options.onValidate`). Each error is a jsoneditor validation error (`{ path, message, ... }`). Empty array means valid. | | `update:text` | `(text: string)` | The raw text changed (may be invalid JSON). Used by `v-model:text`. | | `update:currentMode` | `(mode: string)` | The mode changed. Used by `v-model:currentMode`. | | `mode-change` | `(newMode: string, oldMode: string)` | The mode changed, with the previous mode. | | `update:fullscreen` | `(value: boolean)` | Fullscreen was entered or exited. Used by `v-model:fullscreen`. | | `fullscreen-change` | `(value: boolean)` | Same as `update:fullscreen`, as a plain event. | | `focus` | `(editor: JSONEditor, target: HTMLElement)` | The editor gained focus. | | `blur` | `(editor: JSONEditor, target: HTMLElement)` | The editor lost focus. | | `textSelectionChange` | `(editor: JSONEditor, start: {row, column}, end: {row, column}, text: string)` | Text selection changed in `code`/`text` mode. | | `selectionChange` | `(editor: JSONEditor, start: Node, end: Node)` | Node selection changed in `tree` mode. | | `colorPicker` | `(editor: JSONEditor, parent: HTMLElement, color: string, onChange: (color: string) => void)` | A color picker was requested (`tree` mode, color values). Call `onChange` with the new color. Only overrides jsoneditor's built-in picker when you listen to this event (or pass `options.onColorPicker`). | ## Example ```vue ``` ## Notes * `update:modelValue`, `update:text` and `change` are debounced when the `debounce` prop is set. * `change` and `update:modelValue` are not emitted when the change comes from the parent (an external `v-model` update), which prevents update loops. * Event names `textSelectionChange`, `selectionChange` and `colorPicker` are camelCase. In templates you can write `@text-selection-change` or `@textSelectionChange`. * Callbacks with the same purpose passed in `options` (for example `options.onFocus`) still run in addition to these events. ## Related * [Props](/api/props) * [Methods](/api/methods) --- --- url: https://v3-jsoneditor.netlify.app/api/methods.md description: >- Methods exposed by v3-jsoneditor through a template ref, including getEditor, expandAll, collapseAll, setEditorContent, toggleFullScreen and focus. --- # Methods Methods are exposed on the component instance. Access them with a template ref. | Method | Signature | Description | | --- | --- | --- | | `getEditor` | `() => JSONEditor \| null` | Returns the raw jsoneditor instance, or `null` before the editor is mounted. Use it to call any [jsoneditor method](https://github.com/josdejong/jsoneditor/blob/master/docs/api.md#methods). | | `get` | `() => any` | Returns the current parsed JSON. Throws if the text is not valid JSON. | | `getText` | `() => string` | Returns the raw editor text. | | `validate` | `() => Promise` | Runs validation (schema and `onValidate`) and resolves with the errors; empty array means valid. | | `expandAll` | `() => void` | Expands all nodes. Only has an effect in `tree`, `view` and `form` modes. | | `collapseAll` | `() => void` | Collapses all nodes. Only has an effect in `tree`, `view` and `form` modes. | | `setEditorContent` | `(json: any) => void` | Replaces the editor content with the given JSON value. | | `toggleFullScreen` | `() => void` | Enters or exits fullscreen. Emits `update:fullscreen` and `fullscreen-change`. | | `focus` | `() => void` | Moves keyboard focus into the editor. | ## Example ```vue ``` ## Useful raw jsoneditor methods Through `getEditor()` you can use the full jsoneditor API, for example: | Method | Description | | --- | --- | | `setText(text)` | Set the raw text. Prefer `v-model:text`. | | `setMode(mode)` / `getMode()` | Change or read the mode. Prefer `v-model:currentMode`. | | `setSchema(schema)` | Set a JSON Schema. Prefer `options.schema`, which is reactive. | | `search(text)` | Search in `tree` mode. | | `format()` / `compact()` / `repair()` | Format, compact or repair text in `code`/`text` mode. | ::: warning Avoid calling `getEditor().destroy()` or `getEditor().set()` directly. The component manages the editor lifecycle and content; use `v-model` or `setEditorContent()` instead so the model stays in sync. ::: ## Related * [Props](/api/props) * [Events](/api/events) --- --- url: https://v3-jsoneditor.netlify.app/examples.md description: >- Gallery of live v3-jsoneditor examples with copyable source, from basic v-model usage to schema validation, theming, large data and custom toolbars. --- # Examples Live demos with copyable source. Each demo is a small single-file component you can paste into your app. * [Basic Usage](/examples/basic): a minimal two-way bound editor with `v-model`. * [Read-only Viewer](/examples/read-only): browse JSON in `view` mode, or lock individual fields with `onEditable`. * [Form Mode](/examples/form-mode): edit values while keeping the structure locked. * [JSON Schema Validation](/examples/json-schema): validate against a schema and show live errors. * [Custom Theme](/examples/custom-theme): brand colors with `--vje-*` CSS variables. * [Large JSON](/examples/large-json): 5,000 records with `code` mode and `shallowRef`. * [Custom Toolbar](/examples/custom-toolbar): add Copy JSON and Download buttons with the `#toolbar` slot. Want to try every prop at once? Open the [Playground](/playground). --- --- url: https://v3-jsoneditor.netlify.app/examples/basic.md description: A minimal two-way bound JSON editor with v-model in tree mode. --- # Basic Usage The smallest useful setup: bind a reactive object with `v-model`, start in `tree` mode and give the editor a height. Edit any value and the bound object below updates instantly. ```vue ``` ## How it works * `v-model` keeps `json` and the editor in sync in both directions. * `current-mode="tree"` starts in the tree view; the user can still switch modes from the menu. * `theme="auto"` follows the site's dark mode. Next: [Read-only viewer](/examples/read-only) or the [Usage guide](/guide/usage). --- --- url: https://v3-jsoneditor.netlify.app/examples/read-only.md description: Display JSON as a collapsible, non-editable tree using view mode. --- # Read-only Viewer Use `view` mode to show JSON that users can browse, search and collapse but not change, such as an API response. Restricting `mode-list` to `['view']` ensures users cannot switch to an editable mode. ```vue ``` ## The `read-only` prop To make every mode read-only while still letting users switch between tree and code views, use the `read-only` prop instead: ```vue ``` ## Partially read-only To lock only some fields while keeping others editable, use jsoneditor's `onEditable` option in `tree` mode. Return `false` to lock a node, or an object `{ field, value }` to control the key and value separately: ```vue ``` ::: tip In `code` and `text` modes, jsoneditor calls `onEditable` once with an empty node (no `path`). Returning `false` there makes the whole text read-only, which is why the example uses `path?.[0]`. ::: --- --- url: https://v3-jsoneditor.netlify.app/examples/form-mode.md description: Let users edit values while keeping the JSON structure locked. --- # Form Mode `form` mode looks like `tree` mode, but users can only change values: they cannot add, remove, rename or reorder keys. It is a quick way to build a settings editor without writing a form by hand. Here the mode switcher is limited to `form` and `code` for power users. ```vue ``` ## When to use form mode * Editing configuration where the shape is fixed and only values should change. * Letting non-technical users tweak data without breaking its structure. Combine it with [JSON Schema validation](/examples/json-schema) to also constrain the values. --- --- url: https://v3-jsoneditor.netlify.app/examples/json-schema.md description: Validate JSON against a schema and show the error count from validation-error. --- # JSON Schema Validation Pass a JSON Schema as `options.schema`. Invalid nodes are highlighted in the editor, and the `validation-error` event gives you the list of errors, here used to show a live status. Try fixing the email and age. ```vue ``` ## Notes * `options.schema` is reactive: replace it and the editor revalidates without being re-created. * Add custom rules with `options.onValidate`; its errors are included in `validation-error`. * Parse errors (text that is not JSON at all) are reported through the `error` event instead. Read more in the [Validation guide](/guide/validation). --- --- url: https://v3-jsoneditor.netlify.app/examples/custom-theme.md description: Brand the editor with your own colors using --vje-* CSS variables. --- # Custom Theme The modern themes are driven by `--vje-*` CSS variables. Add a class to the component and override the variables you need: no `!important`, no deep selectors. This demo uses a rose brand palette on top of the `light` theme. ```vue ``` ## Supporting dark mode When using `theme="auto"`, add a dark variant of your palette scoped to the dark state, for example: ```css html.dark .brand-editor { --vje-bg: #1c0a10; --vje-surface: #2a0f18; --vje-border: #4c0519; --vje-text: #ffe4e6; --vje-muted: #fda4af; } ``` All variables are listed in the [Theming guide](/guide/theming#css-variables). --- --- url: https://v3-jsoneditor.netlify.app/examples/large-json.md description: Handle thousands of records smoothly with code mode and shallowRef. --- # Large JSON This demo loads an array of 5,000 objects. jsoneditor handles large documents well when a few precautions are followed. ```vue ``` ## Performance tips * **Start in `code` mode.** The Ace-based code editor virtualizes rendering; `tree` mode creates DOM nodes for every visible entry and is slower to open for big documents. Users can still switch to `tree`. * **Use `shallowRef` instead of `ref`.** A deep `ref` makes Vue wrap every nested object in a reactive proxy, which costs memory and time on every update. With `shallowRef` only `.value` is tracked; replace the whole value to update. * **Debounce updates** with `:debounce="200"` (150 to 300 ms works well) so `v-model` is not re-parsed on every keystroke. * **Avoid deep watchers** on the bound value; listen to `@change` instead. * **Disable features you do not need** in `options`, for example `{ enableSort: false, enableTransform: false, search: false }`. * **Reserve the height** with the `height` prop so the page does not jump while the editor loads. ::: warning In `tree` mode jsoneditor shows large arrays in pages ("show more"), but auto-expansion on update still has a cost. If you need `tree` mode for very large data, call `collapseAll()` through a template ref after loading. ::: --- --- url: https://v3-jsoneditor.netlify.app/examples/custom-toolbar.md description: Add Copy JSON and Download buttons to the menu bar with the --- # Custom Toolbar The `#toolbar` slot renders your own content inside jsoneditor's menu bar, on the right. It receives `{ editor, mode }`, where `editor` is the raw jsoneditor instance, so `editor.get()` returns the current JSON. The slot is re-attached automatically whenever the mode changes. ```vue ``` ## Notes * `editor.get()` throws when the text in `code`/`text` mode is not valid JSON. Wrap it in `try/catch` if you want to show a friendly message, or use `editor.getText()` to export the raw text. * Use `mode` from the slot props to show buttons only in some modes, for example `v-if="mode === 'code'"`. See [Slots](/api/props#slots) in the API reference. --- --- url: https://v3-jsoneditor.netlify.app/ai.md description: >- Give AI assistants and coding agents accurate v3-jsoneditor context with llms.txt, llms-full.txt, per-page Markdown, and ready-to-paste setups for Claude Code, Cursor, Copilot, Codex and chat assistants. --- # Use with AI These docs are built to be read by AI assistants as well as people. Point your assistant at the right source and it will write correct v3-jsoneditor code instead of guessing from outdated examples. ## Machine-readable docs | URL | What it is | | --- | --- | | [`/llms.txt`](https://v3-jsoneditor.netlify.app/llms.txt) | A short index of every page with its title and description, following the [llms.txt](https://llmstxt.org/) convention. Good for agents that fetch pages on demand. | | [`/llms-full.txt`](https://v3-jsoneditor.netlify.app/llms-full.txt) | The complete documentation in one Markdown file. Best for pasting into a chat or loading as context. | | Any page + `.md` | Append `.md` to any docs URL to get that page as clean Markdown, for example [`/guide/usage.md`](https://v3-jsoneditor.netlify.app/guide/usage.md) or [`/api/props.md`](https://v3-jsoneditor.netlify.app/api/props.md). | The Markdown versions contain the full source of every live demo and plain tables for the API, without interactive widgets. ## Copy page / Ask AI Every docs page has a **Copy page** button and an **Ask AI** menu at the top: * **Copy page** copies the current page as Markdown, ready to paste into any assistant. * **Ask AI** opens your assistant of choice (ChatGPT, Claude, Grok, Perplexity, and others) with a prompt that references the page. For DeepSeek and Gemini, which do not accept a prefilled prompt from a link, the prompt is copied to your clipboard and the site opens in a new tab: just paste. ## Claude Code Add this to your project's `CLAUDE.md`: ```md ## v3-jsoneditor This project uses v3-jsoneditor (Vue 3 wrapper for josdejong/jsoneditor). When working with it, fetch https://v3-jsoneditor.netlify.app/llms-full.txt for the current API instead of relying on memory. Import it as `import Vue3Jsoneditor from 'v3-jsoneditor'`. ``` ### Optional: a Claude Code skill For on-demand loading, create `.claude/skills/v3-jsoneditor/SKILL.md`: ```md --- name: v3-jsoneditor description: Use when adding, configuring or debugging the v3-jsoneditor Vue 3 JSON editor component (Vue3Jsoneditor, jsoneditor modes, JSON Schema validation, theming, fullscreen, toolbar slot). --- # v3-jsoneditor Full docs: https://v3-jsoneditor.netlify.app/llms-full.txt (fetch when unsure). Rules: - Import: `import Vue3Jsoneditor from 'v3-jsoneditor'`. Global: `app.use(Vue3Jsoneditor)`. - Bind with `v-model`; any JSON value works (object, array, primitive, null). Clearing the editor in code/text mode emits `null`. - Modes: tree, code (default), form, text, view. Use `current-mode`, `:mode-list`, and `v-model:currentMode`. - Raw text: `v-model:text`. Read-only: `read-only`. Large docs: `:debounce="200"`. - Global defaults: `app.use(Vue3Jsoneditor, { theme: 'auto', height: 500 })`. - Always set `height` (string CSS length or number in px) or give the parent a height. - Pass jsoneditor options via `:options`. Props win over options; callbacks in options run in addition to the component's events. - Validation: `options.schema` (reactive), `options.onValidate`; listen to `@validation-error` (schema) and `@error` (invalid JSON text). - Theme: `theme="light" | "dark" | "auto" | "classic"`; customize with `--vje-*` CSS variables on a class added to the component. - Fullscreen: `plus` shows the button, `v-model:fullscreen`, Esc exits. - Template ref methods: getEditor(), get(), getText(), validate(), expandAll(), collapseAll(), setEditorContent(json), toggleFullScreen(), focus(). - Toolbar: `