TipTap Rich Text Block
The TipTapRichTextBlock is a rich text block based on TipTap (a headless editor built on top of ProseMirror).
It is the successor to the Draft.js-based RichTextBlock and is created with the createTipTapRichTextBlock factory.
It offers several advantages over the old block:
- Built on a maintained library. TipTap is actively developed, while Draft.js is no longer maintained.
- Schema-based validation. TipTap defines the allowed content as a schema, which enables full server-side validation of the content in the API — the old block stored its content unvalidated.
- Easier to extend. New features can be added as TipTap extensions, making it simpler to implement new functionality.
- Standardized, portable content format. Content is stored as a nested ProseMirror JSON tree that mirrors the document structure, which is far easier to work with than Draft.js's flat list of blocks with separate offset-based ranges and a detached
entityMap. The well-structured format is straightforward to render, transform, and reason about — and paves the way for AI-assisted workflows such as generating, editing, or analyzing rich text content.
Roadmap
The TipTap Rich Text Block will replace the Draft.js-based RichTextBlock over the following steps:
- Stable (current). The block is available and follows the regular semantic-versioning guarantees. We recommend it for all projects.
- Removal of the old block. In a future (major) Dextinity version, the Draft.js-based
RichTextBlock(createRichTextBlock) will be deprecated and eventually removed.
We recommend planning the switch to the TipTap Rich Text Block early. New content should use the new block, and existing content can be migrated with the built-in Draft.js migration.
The TipTap Rich Text Block only replaces the Draft.js-based RichTextBlock. It does not replace @dextinity/admin-rte, which remains available for using the rich text editor directly (non-block usage), for instance as a standalone form field.
Replacing the RichTextBlock
Feature comparison
Most features of the Draft.js RichTextBlock have a direct equivalent in the TipTap Rich Text Block.
Draft.js RichTextBlock | TipTap Rich Text Block |
|---|---|
createRichTextBlock | createTipTapRichTextBlock |
rte.supports (SupportedThings[]) | one option per feature (Features) |
bold, italic, strikethrough, sub, sup | bold, italic, strike, sub, sup |
header-one … header-six | textBlocks + the text block type select (Heading 1–6) |
rte.standardBlockType | defaultTextBlock |
ordered-list, unordered-list | orderedList, unorderedList |
history | undoRedoButtons (Admin only) |
link, links-remove | link (pass the link block) |
non-breaking-space, soft-hyphen | nonBreakingSpace, softHyphen |
rte.blocktypeMap (custom block types) | textBlocks[].styles + the styling select |
rte.customInlineStyles | inlineStyles + the inline style select |
rte.listLevelMax | listLevelMax |
rte.maxBlocks | maxTextBlocks |
Site rendering with redraft + Renderers | Site rendering with renderTipTapRichText + nodeMapping/markMapping |
Mail rendering with createRichTextBlock | Mail rendering with createTipTapRichTextBlock (both from @dextinity/mail-react) |
Setup
Like the old block, the TipTap Rich Text Block is configured on the API and in the Admin, and rendered on the site. The factory is available from @dextinity/cms-api and @dextinity/cms-admin under the same name.
Admin
import { createTipTapRichTextBlock } from "@dextinity/cms-admin";
import { LinkBlock } from "./LinkBlock";
export const TipTapRichTextBlock = createTipTapRichTextBlock({ link: LinkBlock });
In the Admin, the style and placeholder options additionally carry rendering information (label and element) that is used to preview them in the editor — see Text block type and styling selects.
API
Unlike the old block, the API now validates the entire block content against the schema derived from your configuration. As a result, the API factory takes more configuration options than the old block did. These options are named exactly like their Admin counterparts, and it is important to keep the two configurations in sync: the API schema must allow everything the Admin editor can produce, otherwise content that looks valid in the editor is rejected when saved.
import { createTipTapRichTextBlock } from "@dextinity/cms-api";
import { LinkBlock } from "./link.block";
export const TipTapRichTextBlock = createTipTapRichTextBlock({ link: LinkBlock });
The factory accepts additional Block Options such as the block name, like the old one:
export const TipTapRichTextBlock = createTipTapRichTextBlock(
{ link: LinkBlock },
{ name: "TipTapRichText" },
);
Site
There is no site factory. Instead, @dextinity/site-react / @dextinity/site-nextjs provide the renderTipTapRichText render helper (and a hasTipTapRichTextContent helper for preview skeletons). You write your own block component that maps TipTap nodes and marks to your components:
"use client";
import {
hasTipTapRichTextContent,
PreviewSkeleton,
type PropsWithData,
renderTipTapRichText,
type TipTapMarkHandler,
type TipTapNodeHandler,
} from "@dextinity/site-nextjs";
import { LinkBlockData, TipTapRichTextBlockData } from "@src/blocks.generated";
import { LinkBlock } from "./LinkBlock";
const nodeMapping: Record<string, TipTapNodeHandler> = {
// Render each text block by its name, and handle the node types the defaults don't cover.
textBlock: ({ node, children }) =>
node.attrs?.textBlock === "heading-1" ? <h1>{children}</h1> : <p>{children}</p>,
};
const markMapping: Record<string, TipTapMarkHandler> = {
link: ({ mark, children }) => {
const linkData = mark.attrs?.data as LinkBlockData | undefined;
return linkData ? <LinkBlock data={linkData}>{children}</LinkBlock> : <>{children}</>;
},
};
export function TipTapRichTextBlock({ data }: PropsWithData<TipTapRichTextBlockData>) {
const content = data.tipTapContent;
return (
<PreviewSkeleton
title="RichText"
type="rows"
hasContent={hasTipTapRichTextContent(content)}
>
{renderTipTapRichText({ content, nodeMapping, markMapping })}
</PreviewSkeleton>
);
}
renderTipTapRichText ships default mappings for the standard nodes and marks (bulletList → <ul>, orderedList → <ol>, listItem → <li>, bold → <strong>, italic → <em>, strike → <s>, superscript → <sup>, subscript → <sub>, and the special-character nodes). A textBlock renders by its name: heading-1 to heading-6 as <h1> to <h6>, anything else as <p>. Those are the text blocks configured by default — which tag any other one renders as follows from the block's configuration, which the site doesn't have, so a block that renames a text block or adds one needs its own textBlock handler. Your nodeMapping/markMapping are merged over the defaults; supply handlers for anything the defaults don't cover (link, inlineStyle, cmsBlock/cmsInlineBlock, placeholder).
TipTapNode is structurally compatible with TipTap's own JSONContent type.
A JSONContent value can be rendered with renderTipTapRichText, and the block data can be passed to TipTap utilities such as generateHTML() — no cast needed in either direction.
Features
Every editor feature has its own option in the root options object, similar to TipTap's StarterKit. Most features are enabled by default and are turned off by passing false:
| Option | Default | Available in |
|---|---|---|
bold | true | API + Admin |
italic | true | API + Admin |
underline | false | API + Admin |
strike | true | API + Admin |
sub | true | API + Admin |
sup | true | API + Admin |
orderedList | true | API + Admin |
unorderedList | true | API + Admin |
nonBreakingSpace | true | API + Admin |
softHyphen | true | API + Admin |
textAlign | false | API + Admin |
undoRedoButtons | true | Admin only |
The text block types the content may consist of are configured separately, through textBlocks.
Links are the exception to the boolean options: link takes the link block that is used for links, and passing it enables the feature. Links are disabled by default.
export const TipTapRichTextBlock = createTipTapRichTextBlock({
// Turn a feature off
strike: false,
// Turn a feature on that is disabled by default
underline: true,
// Enable links by passing the link block
link: LinkBlock,
});
The limits on the document as a whole aren't tied to a single feature and stay at the root of the options object: maxTextBlocks limits the number of top-level text blocks and listLevelMax the nesting depth of lists.
Migrating existing content
Existing content stored by the Draft.js RichTextBlock ({ draftContent: { blocks, entityMap } }) can be migrated in place. Enable the built-in migration with the migrateFromDraftJs option on the API factory:
export const TipTapRichTextBlock = createTipTapRichTextBlock({
link: LinkBlock,
migrateFromDraftJs: true,
});
To perform an in-place replacement, register the TipTap block wherever the old RichTextBlock was used (e.g. under the same key in a BlocksBlock's supportedBlocks). Existing block instances are then live-migrated from draftContent to tipTapContent the next time they are loaded from the database.
The migration converts:
- inline styles
BOLD,ITALIC,STRIKETHROUGH,SUP,SUB→ the corresponding TipTap marks, header-one…header-six→ the text blocks with the matching heading tag,- ordered/unordered list items → TipTap lists,
LINKentities → TipTaplinkmarks,/→ non-breaking-space / soft-hyphen nodes.
It uses the block's enabled features and its textBlocks and maxTextBlocks options to build the target schema and validates the result. The conversion is best effort: if validation fails, it falls back to a stripped-down plain-text document in production (logging a warning) and throws in development so you can catch problems early.
Because the API never validated the old block's content and the TipTap block performs a complete re-validation, the migration must be tested very carefully against real production content before going live. Content that was accepted by the old block may now fail validation and be stripped down. Run the migration on a copy of your production data and review the result before deploying.
Mapping custom Draft.js styles
If the old block used custom block types (via blocktypeMap) or custom inline styles (via customInlineStyles), map them to their TipTap equivalents by passing an object instead of true:
export const TipTapRichTextBlock = createTipTapRichTextBlock({
link: LinkBlock,
textBlocks: [{ name: "paragraph", tag: "p", styles: [{ name: "paragraph200" }] }],
inlineStyles: [{ name: "highlight" }],
migrateFromDraftJs: {
// Map the Draft.js `blocktypeMap` entry to a text block and its `textBlockStyle`.
textBlockMap: {
"paragraph-small": { textBlock: "paragraph", textBlockStyle: "paragraph200" },
},
// Map a Draft.js `customInlineStyles` name to a TipTap `inlineStyle`.
inlineStyleMap: { HIGHLIGHT: "highlight" },
},
});
Every mapping names the text block the Draft.js block becomes, which matters where the block type doesn't carry that information — a custom block type such as headline450 that was rendered as <h2> would otherwise become a paragraph and lose its semantic tag:
export const TipTapRichTextBlock = createTipTapRichTextBlock({
textBlocks: [{ name: "heading-2", tag: "h2", styles: [{ name: "headline450" }] }],
migrateFromDraftJs: {
textBlockMap: {
headline450: { textBlock: "heading-2", textBlockStyle: "headline450" },
},
},
});
textBlock accepts the name of any configured text block, and an unknown name throws. textBlockStyle is optional — leave it out for a text block that offers no styles. A Draft.js block type that isn't mapped becomes the text block its own type implies: header-one–header-six keep their heading level, everything else becomes a paragraph.
Custom list block types — for instance a blocktypeMap entry with supportedBy: "unordered-list" — would otherwise become paragraphs too. Map them in listItemMap to the list they become items of and the list style the item carries:
const listSizes = { styles: [{ name: "small" }, { name: "large" }] };
export const TipTapRichTextBlock = createTipTapRichTextBlock({
unorderedList: listSizes,
orderedList: listSizes,
migrateFromDraftJs: {
listItemMap: {
"unordered-list-item-small": { list: "unordered", textBlockStyle: "small" },
"unordered-list-item-large": { list: "unordered", textBlockStyle: "large" },
"ordered-list-item-small": { list: "ordered", textBlockStyle: "small" },
"ordered-list-item-large": { list: "ordered", textBlockStyle: "large" },
},
},
});
Consecutive items of the same list stay one list, whatever their style, and keep their nesting. textBlockStyle must be one of the list's styles, and the list must be enabled. The built-in unordered-list-item and ordered-list-item can't be mapped, and neither can a block type that is in textBlockMap. Each of these throws. To give the built-in list items a style, set the list's defaultStyle.
New features
Beyond replacing the old block, the TipTap Rich Text Block adds capabilities the Draft.js block did not have.
Text block type and styling selects
The editor toolbar offers two dropdowns to structure and style text blocks:
- Text block type — which of the configured text blocks the current block is. Shown when more than one is configured.
- Styling — a named style applied to the current text block. This decouples semantics ("this is a paragraph") from appearance ("small paragraph"), so editors pick a type and a style independently. Shown when the current text block (or the list its content sits in) offers styles.
There is a matching inline style dropdown for inlineStyles, which applies named styles to a text selection.
A text block's styles are configured on the API (name) and in the Admin (additionally label for the dropdown and element for the editor preview). Text blocks that offer the same style share its definition, which makes the shared set explicit instead of implying it through repeated names:
const listStyles = [{ name: "list300" }, { name: "list200" }];
export const TipTapRichTextBlock = createTipTapRichTextBlock({
link: LinkBlock,
textBlocks: [
{
name: "paragraph",
tag: "p",
styles: [{ name: "paragraph300" }, { name: "paragraph200" }],
},
{ name: "heading-1", tag: "h1" },
],
orderedList: { styles: listStyles },
unorderedList: { styles: listStyles },
inlineStyles: [{ name: "highlight" }, { name: "tag", appliesTo: ["paragraph"] }],
});
import { FormattedMessage } from "react-intl";
const paragraphStyles: TipTapTextBlockStyle[] = [
{
name: "paragraph300",
label: (
<FormattedMessage id="tipTapRichTextBlock.paragraph300" defaultMessage="Paragraph" />
),
element: (props) => <p style={{ fontSize: 18, lineHeight: "26px" }} {...props} />,
},
{
name: "paragraph200",
label: (
<FormattedMessage
id="tipTapRichTextBlock.paragraph200"
defaultMessage="Paragraph Small"
/>
),
element: (props) => <p style={{ fontSize: 15, lineHeight: "22px" }} {...props} />,
},
];
export const TipTapRichTextBlock = createTipTapRichTextBlock({
link: LinkBlock,
textBlocks: [
{
name: "paragraph",
tag: "p",
label: (
<FormattedMessage id="tipTapRichTextBlock.paragraph" defaultMessage="Paragraph" />
),
styles: paragraphStyles,
},
{
name: "heading-1",
tag: "h1",
label: (
<FormattedMessage id="tipTapRichTextBlock.heading1" defaultMessage="Heading 1" />
),
},
],
inlineStyles: [
{
name: "highlight",
label: (
<FormattedMessage id="tipTapRichTextBlock.highlight" defaultMessage="Highlight" />
),
element: (props) => <span style={{ backgroundColor: "#fff3cd" }} {...props} />,
},
],
});
A style's element receives the tag of the text block it is applied to, so one style can be shared by text blocks with different tags: element: (props, Tag) => <Tag {...props} />.
An inline style's appliesTo limits it to the named text blocks, plus "ordered-list" and "unordered-list" for a list item's content.
Default styles
A text block (or list) with a defaultStyle has no "no style" state: the styling select drops its Default entry, and every text block of that type carries one of the styles. Text blocks without a defaultStyle keep the Default entry, so both can sit side by side:
export const TipTapRichTextBlock = createTipTapRichTextBlock({
textBlocks: [
{ name: "heading-1", tag: "h1", styles: headlineStyles, defaultStyle: "headline300" },
{ name: "heading-2", tag: "h2", styles: headlineStyles },
],
});
The style is applied to new content, to a text block the editor converts through the type select, and to any text block the editor creates without one — pressing Enter at the end of a text block, using the Mod-Alt-<level> shortcuts, or pasting. Switching the type keeps a style the new text block also offers and falls back to its defaultStyle otherwise, whether the switch comes from the toolbar or from a keyboard shortcut.
defaultStyle must be one of the text block's styles, otherwise an error is thrown. It only exists next to styles, not next to a text block's own element.
Content written before a defaultStyle was configured carries no style. The API fills in the defaultStyle whenever it reads such a text block, inside a list item the list's, so the site always receives the style's name and needs no migration for it.
Text blocks without a style choice
A text block that needs no style choice carries its own element instead of styles. The two exclude each other, and a text block with neither is rendered as its plain tag:
export const TipTapRichTextBlock = createTipTapRichTextBlock({
textBlocks: [
{
name: "display",
tag: "h1",
label: <FormattedMessage id="tipTapRichTextBlock.display" defaultMessage="Display" />,
element: (props, Tag) => <Tag style={{ fontSize: 64 }} {...props} />,
},
],
});
On the site, the chosen style is available as the textBlockStyle attribute (block styles) or the inlineStyle mark type (inline styles), which you resolve to your own components in nodeMapping/markMapping:
const nodeMapping: Record<string, TipTapNodeHandler> = {
paragraph: ({ node, children }) => (
<Typography variant={(node.attrs?.textBlockStyle as string | null) ?? undefined}>
{children}
</Typography>
),
};
Text blocks
textBlocks configures the text block types the content may consist of, in the order the editor's text block type select offers them. Each entry has a name that identifies it, a tag it is stored and rendered as (p, or h1–h6), and — in the Admin — a label for the select. It defaults to a paragraph plus a heading for every level.
export const TipTapRichTextBlock = createTipTapRichTextBlock({
textBlocks: [
{ name: "paragraph", tag: "p" },
{ name: "display", tag: "h1" },
{ name: "heading-1", tag: "h1" },
{ name: "heading-2", tag: "h2" },
],
defaultTextBlock: "paragraph",
});
export const TipTapRichTextBlock = createTipTapRichTextBlock({
textBlocks: [
{
name: "paragraph",
tag: "p",
label: <FormattedMessage id="tipTapRichText.paragraph" defaultMessage="Paragraph" />,
},
{
name: "display",
tag: "h1",
label: <FormattedMessage id="tipTapRichText.display" defaultMessage="Display" />,
},
{
name: "heading-1",
tag: "h1",
label: <FormattedMessage id="tipTapRichText.heading1" defaultMessage="Heading 1" />,
},
{
name: "heading-2",
tag: "h2",
label: <FormattedMessage id="tipTapRichText.heading2" defaultMessage="Heading 2" />,
},
],
defaultTextBlock: "paragraph",
});
Every paragraph and heading is stored as one textBlock node that names its text block — the tag lives in the configuration, not in the content:
{
"type": "textBlock",
"attrs": { "textBlock": "heading-2" },
"content": [{ "type": "text", "text": "Headline" }]
}
Several text blocks may therefore share a tag, as display and heading-1 do above: both render as an h1, and the name tells them apart. That covers a design where a display headline sits above a regular heading 1 without being a style of it. On the site, one handler renders every text block by its name:
const nodeMapping: Record<string, TipTapNodeHandler> = {
textBlock: ({ node, children }) => (
<Headline variant={node.attrs?.textBlock}>{children}</Headline>
),
};
Because the name is all the content carries, renaming or removing a text block leaves the content it belongs to without a tag to render as: the API rejects it, and it needs a migration. Changing a text block's tag, on the other hand, takes effect without one.
Content stored before the textBlock node existed holds a paragraph or heading node instead. A vendor migration converts it when the block is loaded, resolving the text block from the node's tag. Since the vendor migrations run before the block's own, a project migration always sees the textBlock node — one written against { type: "heading", attrs: { level } } has to be changed to match { type: "textBlock", attrs: { textBlock } }.
defaultTextBlock names the text block new content starts with, so the select's order can be chosen independently of it. It defaults to the first entry.
The textBlocks and defaultTextBlock options must match between the API and the Admin, otherwise the API rejects content the editor produces.
Heading-only blocks
Leaving the p text block out results in a block that only holds headings — the TipTap equivalent of the Draft.js pattern of a RichTextBlock restricted to header-* block types with a standardBlockType, for instance the headline part of a heading block:
export const TipTapHeadlineBlock = createTipTapRichTextBlock(
{
textBlocks: [
{ name: "heading-2", tag: "h2" },
{ name: "heading-3", tag: "h3" },
{ name: "heading-4", tag: "h4" },
],
defaultTextBlock: "heading-3",
maxTextBlocks: 1,
},
{ name: "TipTapHeadline" },
);
The editor starts with an H3, the text block type select only offers the configured headings, and Mod-Alt-2/3/4 switch between them (levels no text block uses have no shortcut).
Lists are disabled without a p text block, because a list item's content starts with a paragraph. Enabling one explicitly (orderedList: true) throws, as does an empty textBlocks array — that would leave no text block type at all.
The API rejects content the configuration doesn't allow: a text block that isn't configured, whether it was removed, renamed, or never existed. Narrowing textBlocks for a block that already holds content therefore requires a migration.
Content written before the text blocks became one node — paragraphs and headings with a level — does not fit the current schema either. How it is converted is still being decided; until then this block only reads content the current editor wrote.
Text alignment
The textAlign option adds toolbar buttons that align paragraphs and headings left, center, right, or justified, with the shortcuts Mod-Shift-L, Mod-Shift-E, Mod-Shift-R, and Mod-Shift-J. A text block without an alignment counts as left-aligned, and clicking the button of the active alignment changes nothing.
Not every site supports every alignment, for instance justified text. An object enables only the alignments it sets to true:
export const TipTapRichTextBlock = createTipTapRichTextBlock({
link: LinkBlock,
textAlign: { left: true, center: true },
});
The textAlign option must match between the API and the Admin, otherwise the API rejects content the editor produces. The API also rejects content that uses an alignment that isn't enabled, so disabling an alignment for a block that already holds content requires a migration.
The alignment is stored in the text block's textAlign attribute, and the default textBlock handler of renderTipTapRichText renders it as a text-align style. A custom textBlock handler has to apply the alignment itself:
const nodeMapping: Record<string, TipTapNodeHandler> = {
textBlock: ({ node, children }) => {
const textAlign = node.attrs?.textAlign as CSSProperties["textAlign"] | null | undefined;
return <p style={textAlign ? { textAlign } : undefined}>{children}</p>;
},
};
Child blocks
The TipTap Rich Text Block can embed other blocks directly into the rich text via the childBlocks option. This lets editors insert, for example, a product teaser between paragraphs, or an inline product price within a sentence — something the Draft.js block could not do.
Child blocks are keyed by a stable key. The key (not the block's name) is stored in the content, so blocks can be renamed or swapped without invalidating existing content. Each entry specifies a display:
"block"— a standalone block element on its own line,"inline"— inline within the surrounding text.
The same configuration is used on the API and in the Admin:
import { createTipTapRichTextBlock } from "@dextinity/cms-api";
export const TipTapRichTextBlock = createTipTapRichTextBlock({
link: LinkBlock,
childBlocks: {
productPrice: { block: ProductPriceBlock, display: "inline" },
productTeaser: { block: ProductTeaserBlock, display: "block" },
},
});
import { createTipTapRichTextBlock } from "@dextinity/cms-admin";
export const TipTapRichTextBlock = createTipTapRichTextBlock({
link: LinkBlock,
childBlocks: {
productPrice: { block: ProductPriceBlock, display: "inline" },
productTeaser: { block: ProductTeaserBlock, display: "block" },
},
});
Child-block data is validated against each block's input on the API (just like top-level blocks) and exposed as nested blocks, so block loaders and transformers recurse into them. On the site, render them via nodeMapping by inspecting the node's blockType attribute:
const renderCmsBlock: TipTapNodeHandler = ({ node }) => {
if (node.attrs?.blockType === "productPrice") {
return <ProductPriceBlock data={node.attrs?.data as ProductPriceBlockData} />;
}
if (node.attrs?.blockType === "productTeaser") {
return <ProductTeaserBlock data={node.attrs?.data as ProductTeaserBlockData} />;
}
return null;
};
const nodeMapping: Record<string, TipTapNodeHandler> = {
cmsBlock: renderCmsBlock, // block-level child blocks
cmsInlineBlock: renderCmsBlock, // inline child blocks
};