Configuration

The editor is configured per field (a config dict on the widget) and project-wide (Django settings). Per-field config is merged over the project default, then written to the textarea's data-tiptap-config attribute as JSON; the JS glue fills in defaults for any omitted key.

Config keys

Key	Type	Notes
height	str	Editor min-height, e.g. "400px".
locale	str	"en" or "sv" built in; add more with registerLocale.
manualMount	bool	Opt the field out of auto-mount (initial scan + observer); mount it yourself after registering renderers. See Theming → Load order.
enterKey	str	Enter / Shift-Enter behaviour: "paragraph" (default — Enter splits into a new paragraph, Shift-Enter inserts a line break), "hardBreak" (Enter inserts a <br>), or "swap" (exchange the two).
toolbar	list[list[str]]	Groups of button keys. Omit for the default.
extensions	list[str]	Extension names. Built-ins are always on; list custom ones (and add them to TIPTAP_EXTRA_EXTENSIONS).
linkProtocols	list[str]	Allowed link protocols. Default ["http","https","mailto","tel"].
imageUploadUrl	str	Enables image upload (see Contracts).
imageListUrl	str	Enables the library picker.
imageFileTypes	str	Comma-separated extensions for the upload dialog, e.g. "png,jpg,gif".
fontFamilies	list[str]	Presets for the fontFamily dropdown; each a full CSS font stack (label = first segment, quotes stripped). Omit for the built-in list.
fontSizes	list[str]	Presets for the fontSize dropdown; each a CSS length like "16px" (label = value without px). Omit for the built-in list.
textColors	list[str]	Swatches for the color (text color) dropdown; each any CSS color. Omit for the built-in palette.
highlightColors	list[str]	Swatches for the highlight (background) dropdown; each any CSS color. Omit for the built-in palette.
mergeTags	list[{label, value}]	Items for the merge-tags menu; value is inserted verbatim.

Unknown top-level keys, and extension names that are neither built in nor in TIPTAP_EXTRA_EXTENSIONS, raise ImproperlyConfigured — typos fail loudly.

TipTapWidget(config={
    "height": "500px",
    "toolbar": [["bold", "italic", "link"], ["bulletList", "orderedList"]],
    "imageUploadUrl": "/editor/upload/",
    "fontFamilies": ["Arial, sans-serif", "Roboto, sans-serif"],
    "fontSizes": ["12px", "14px", "16px", "20px", "28px"],
    "textColors": ["#1f2329", "#e03e2d", "#3598db"],
    "highlightColors": ["#fff3a3", "#c8f7c5", "#bfe3ff"],
    "mergeTags": [{"label": "First name", "value": "{{ first_name }}"}],
})

Toolbar buttons

undo redo · bold italic underline strike code · fontSize fontFamily color highlight · h1 h2 h3 paragraph · bulletList orderedList blockquote · alignLeft alignCenter alignRight alignJustify · image table · link unlink clearFormatting · sourceView · mergeTags (opt-in).

A group is an inner array; groups render with separators. Register your own buttons with ui.registerButton.

Settings

Setting	Default	Purpose
TIPTAP_DEFAULT_CONFIG	{}	Config merged under every widget's per-field config.
TIPTAP_ASSET_MODE	"bundle"	"bundle" or "external" — see Asset modes.
TIPTAP_IMPORT_MAP	CDN default	External mode: bare-specifier → URL map.
TIPTAP_EXTRA_EXTENSIONS	[]	Extra extension names accepted by config validation.

TIPTAP_DEFAULT_CONFIG = {"height": "450px", "locale": "sv"}

Settings are read lazily — importing the package never touches Django settings.