django-editorjs-fields

Django integration for Editor.js — a block-style WYSIWYG editor.

• Django: 2.2 – 6.x
• Python: 3.8 – 3.13
• Editor.js: 2.31.6
• 

---

---

Table of Contents

• Installation
• Quick start
• Rendering in templates
• Field arguments
• Custom plugins
• Forms and widgets
• Image uploads
• Dark theme
• Settings
• Support

---

Installation

pip install django-editorjs-fields

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'django_editorjs_fields',
]

Upgrade

pip install django-editorjs-fields --upgrade
python manage.py collectstatic

---

Quick start

Define fields in your model:

from django.db import models
from django_editorjs_fields import EditorJsJSONField, EditorJsTextField


class Post(models.Model):
    # Stores data as JSON (Django >= 3.1)
    body = EditorJsJSONField(null=True, blank=True)

    # Stores data as serialized JSON string (any Django version)
    body_text = EditorJsTextField(null=True, blank=True)

Don't forget to add URLs for image upload and link metadata:

# urls.py
from django.urls import path, include

urlpatterns = [
    # ...
    path('editorjs/', include('django_editorjs_fields.urls')),
]

See the full example project: example/

---

Rendering in templates

Use the editorjs template filter to render stored blocks as HTML:

{% load editorjs %}
{{ post.body|editorjs }}

The filter escapes all user content to prevent XSS. Use the raw block type if you need to render trusted HTML.

---

Field arguments

Both EditorJsJSONField and EditorJsTextField accept all arguments of their base Django fields (JSONField / TextField) plus:

Argument	Description	Default
plugins	List of Editor.js plugin packages	EDITORJS_DEFAULT_PLUGINS
tools	Tool configuration map (docs)	EDITORJS_DEFAULT_CONFIG_TOOLS
config	Editor.js config overrides (autofocus, readOnly, placeholder, etc.)	{}

Config keys are passed directly to the Editor.js constructor. Refer to the official docs for all options.

---

Custom plugins

Pass a custom plugin list and tool configuration to the field:

body = EditorJsJSONField(
    plugins=[
        "@editorjs/image",
        "@editorjs/header",
        "@editorjs/code@2.6.0",      # pin a specific version
        "@editorjs/list@latest",
        # Full URLs work for plugins hosted outside npm/jsDelivr
        "https://cdn.jsdelivr.net/gh/some-repo/plugin@main/index.js",
    ],
    tools={
        "Image": {
            "config": {
                "endpoints": {
                    "byFile": "/my-upload-endpoint/"
                }
            }
        },
    },
    config={"minHeight": 500},
)

Registering custom plugin keys

If your custom plugin is not in the built-in PLUGINS_KEYS map, register it in settings:

# settings.py
EDITORJS_PLUGINS_KEYS = {
    'my/custom-plugin': 'MyCustomPlugin',
}

This map is merged with built-in defaults — you only need entries for your own plugins.

Built-in plugins

The following plugins are enabled by default:

EDITORJS_DEFAULT_PLUGINS

(
    '@editorjs/paragraph',
    '@editorjs/image',
    '@editorjs/header',
    '@editorjs/list',
    '@editorjs/checklist',
    '@editorjs/quote',
    '@editorjs/raw',
    '@editorjs/code',
    '@editorjs/inline-code',
    '@editorjs/embed',
    '@editorjs/delimiter',
    '@editorjs/warning',
    '@editorjs/link',
    '@editorjs/marker',
    '@editorjs/table',
)

EDITORJS_DEFAULT_CONFIG_TOOLS

{
    'Image': {
        'class': 'ImageTool',
        'inlineToolbar': True,
        "config": {
            "endpoints": {
                "byFile": reverse_lazy('editorjs_image_upload'),
                "byUrl": reverse_lazy('editorjs_image_by_url')
            }
        },
    },
    'Header': {
        'class': 'Header',
        'inlineToolbar': True,
        'config': {
            'placeholder': 'Enter a header',
            'levels': [2, 3, 4],
            'defaultLevel': 2,
        }
    },
    'Checklist': {'class': 'Checklist', 'inlineToolbar': True},
    'List': {'class': 'EditorjsList', 'inlineToolbar': True},
    'Quote': {'class': 'Quote', 'inlineToolbar': True},
    'Raw': {'class': 'RawTool'},
    'Code': {'class': 'CodeTool'},
    'InlineCode': {'class': 'InlineCode'},
    'Embed': {'class': 'Embed'},
    'Delimiter': {'class': 'Delimiter'},
    'Warning': {'class': 'Warning', 'inlineToolbar': True},
    'LinkTool': {
        'class': 'LinkTool',
        'config': {
            'endpoint': reverse_lazy('editorjs_linktool'),
        }
    },
    'Marker': {'class': 'Marker', 'inlineToolbar': True},
    'Table': {'class': 'Table', 'inlineToolbar': True},
}

---

Forms and widgets

Use EditorJsWidget in forms:

from django import forms
from django_editorjs_fields import EditorJsWidget


class PostForm(forms.ModelForm):
    class Meta:
        model = Post
        fields = '__all__'
        widgets = {
            'body': EditorJsWidget(
                plugins=["@editorjs/image", "@editorjs/header"],
                config={'minHeight': 200},
            )
        }

---

Image uploads

Include the package URLs (see Quick start). Images are saved to MEDIA_ROOT/uploads/images/YYYY/MM/ by default.

In development (DEBUG=True), also serve media files:

# urls.py
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

In production, configure your web server (nginx, Apache) to serve MEDIA_URL.

---

Dark theme

The editor adapts to the system dark mode via prefers-color-scheme. In Django admin (4.2+), it also respects the theme toggle button (data-theme="dark").

---

Settings

All settings go in your project's settings.py.

Setting	Description	Default	Type
EDITORJS_DEFAULT_PLUGINS	Plugin package list	See above	list, tuple
EDITORJS_DEFAULT_CONFIG_TOOLS	Tool configuration map	See above	dict
EDITORJS_PLUGINS_KEYS	Custom plugin → tool key map (merged with defaults)	{}	dict
EDITORJS_VERSION	Editor.js version	'2.31.6'	str
EDITORJS_IMAGE_UPLOAD_PATH	Base upload directory	'uploads/images/'	str
EDITORJS_IMAGE_UPLOAD_PATH_DATE	Date subdirectory format	'%Y/%m/'	str
EDITORJS_IMAGE_NAME_ORIGINAL	Keep original filename	False	bool
EDITORJS_IMAGE_NAME	Filename generator callable	token_urlsafe(8)	callable
EDITORJS_EMBED_HOSTNAME_ALLOWED	Allowed hostnames for embed validation	See source	list, tuple

---

Support

Report issues on GitHub