Quickstart

Install django-json-widget:

pip install django-json-widget

Add it to your INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'django_json_widget',
    ...
)

Add the widget in your admin.py:

from django.contrib import admin
from django.db.models import JSONField
from django_json_widget.widgets import JSONEditorWidget
from .models import YourModel


@admin.register(YourModel)
class YourModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        JSONField: {'widget': JSONEditorWidget},
    }

You can also add the widget in your forms.py:

from django import forms
from django_json_widget.widgets import JSONEditorWidget
from .models import YourModel


class YourForm(forms.ModelForm):
    class Meta:
        model = YourModel

        fields = ('jsonfield',)

        widgets = {
            'jsonfield': JSONEditorWidget
        }

Wagtail

For a Django JSONField on a Wagtail page or snippet, pass the widget to FieldPanel. Add django_json_widget to INSTALLED_APPS as above.

from django.db import models
from wagtail.admin.panels import FieldPanel
from wagtail.models import Page
from django_json_widget.widgets import JSONEditorWidget


class ConfigurationPage(Page):
    configuration = models.JSONField(default=dict, blank=True)

    content_panels = Page.content_panels + [
        FieldPanel(
            'configuration',
            widget=JSONEditorWidget(width='100%'),
        ),
    ]

Wagtail includes the widget’s JavaScript and CSS through form media. The same FieldPanel configuration can be used on a child model displayed through InlinePanel; editors initialize when rows are added. Django validates the submitted JSON, including invalid or cleared input.

This integration is tested with Wagtail 7.2 and Django 5.2. It covers model fields rendered by panels. Using the widget inside a custom StreamField block requires a Wagtail Telepath widget adapter.

Configuration

You can customize the JSONEditorWidget with the following options:

• width: Width of the editor as a string with CSS size units (px, em, % etc). Defaults to 90%.

• height: Height of the editor as a string CSS size units. Defaults to 550px.

• options: A dict of options accepted by the JSON editor. Options that require functions (eg. onError) are not supported.

• mode (deprecated): The default editor mode. This argument is redundant because it can be specified as a part of options. Preserved for backwards compatibility with version 0.2.0.

• attrs: HTML attributes to be applied to the wrapper element. See the Django Widget documentation.

Content Security Policy

The widget loads its executable initialization code from a static JavaScript file. Its initial value is embedded in a non-executable application/json script element. However, the bundled JSONEditor and its Ace code editor are not fully compatible with a strict Content Security Policy (CSP):

• The widget and editor use inline styles, and Ace injects style elements. A policy that disallows inline styles can prevent the editor from displaying correctly.

• The default code mode creates a blob: worker. A restrictive worker-src can block it.

• JSON schema validation compiles schemas using JavaScript’s Function constructor. A script-src that disallows 'unsafe-eval' blocks this.

Consequently, allowing only 'self' for scripts and styles is not sufficient for all widget features. The CSP directives and relaxations needed depend on the chosen editor modes and options; test the actual configuration with CSP enforcement before deploying. Allowing inline styles, blob: workers, or 'unsafe-eval' weakens a policy, so projects that cannot accept those exceptions should use a different editor or provide compatible assets via JSON_EDITOR_JS and JSON_EDITOR_CSS.

Accessing JsonEditor Instance

The JsonEditor instance is automatically exposed for external access through two methods:

1. Window object: Available as window['FIELD_ID_editor'] where FIELD_ID is the field’s HTML ID

2. DOM element: Available as container.jsonEditor property on the widget’s container element

Example usage for external JavaScript access:

// Access via window object
var editor = window['id_jsonfield_editor'];
editor.set({'key': 'new value'});

// Access via DOM element
var container = document.getElementById('id_jsonfield');
var editor = container.jsonEditor;
editor.set({'key': 'new value'});

This allows you to programmatically call JsonEditor methods like set(), get(), update(), etc. from custom JavaScript code running in your admin pages or forms.

JSONEditorWidget widget

Before:

After:

Development Guide

Read the contribution guide.

Credits

Tools used in rendering this package:

• Cookiecutter

• cookiecutter-djangopackage

2.2.0 (2026-11-13)

• Added CSP guide.

• Implemented Wagtail support.

• Fixed inline editors.

2.1.1 (2025-12-12)

• Issue #108: respect Django admin color scheme setting for JSON editor.

2.1.0 (2025-10-24)

• Issue #114: expose editor instance to window object and DOM element.

2.0.4 (2025-10-11)

• Fix dark mode CSS support #107

2.0.3 (2025-07-29)

2.0.2 (2025-07-28)

• Fix Version 2.0.1 causes rendering HTML scripts issue #80

2.0.1 (2024-03-02) ——————=

• Fixed Version 2.0.0 causes issues with Django 4.x due to missing sourcemaps issue #83

2.0.0 (2024-03-24)

• Fix default paths for static files #53

• Stop declaring support for Django versions before 3.2 #65

• Avoid HTML injection via unsafe JSON injection #64

• Remove source map reference from JS bundle #70

• Add dark mode CSS support #82

• Updated documentation

1.1.1 (2021-02-17)

• Fix for issue #51, updates the bundled libs to 9.1.9 and additional notes for Django 3.1 changes

1.1.0 (2021-02-05)

• Added functionality to override version of JSONEditor to use

• update readme for django 3.1

1.0.1 (2020-04-17)

• Stop resolving paths to the static files

1.0.0 (2020-01-16)

• Update Makefile

• Make Stable the project

0.3.0 (2020-01-16)

• Update requirements.txt

• Fixed static to work with CDN tools like django-storages

• Make widget more configurable

• Fixed an incompatibility with Python 2.7

• update jsoneditor to latest version