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:

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/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',
)

{
    '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.

Support

Report issues on GitHub