RichTextEditor

When to use

Long-form content that operators lay out themselves and the front end renders verbatim: campaign rules, brand stories, product descriptions, newsletter articles. There is a single test: the value going in and out is an HTML string (the database stores HTML, and the front end feeds it straight into v-html or a mini-program rich-text).

Use MarkdownEditor when the value is Markdown, and Textarea for plain multiline text. Do not mount an editor merely to display existing HTML: opening the content normalizes it against the editor schema.

Do not route around this with conversion: html → md is lossy. <span style="color:#e4393c">, <p style="text-align:center">, <table>, and <iframe> have no Markdown equivalent, so one round trip strips the centering and the red highlights from an article an operator only wanted to fix a typo in.

Import

Props

RichTextToolbarItem is "bold" | "italic" | "underline" | "strike" | "heading" | "fontSize" | "color" | "backgroundColor" | "align" | "bulletList" | "orderedList" | "blockquote" | "link" | "image" | "table" | "clear" | "divider".

LegacyHtmlOptions

Events

Height cap

Without a cap the editor's height simply follows the length of the body. In an admin app "one field is a whole long article" is the norm - privacy policies, terms of service, campaign rules, product descriptions - and legacy content routinely runs to several thousand words. Measured on a real page, an 8,000-word body stretched the content area to nearly 9,000px and the page to over 12,000px, which left the Save button entirely outside the viewport; with two editors on one page, a long first one pushes the second far below the fold.

One cap is enough, and the scrolling lands on the body while the toolbar stays put:

The two props are one thing in two units, so pick one; when both are given maxHeight wins and the component warns in development.

Only the library can provide this tier. Wrapping max-h-[480px] overflow-y-auto around the component in product code can only wrap the whole shell, and the toolbar lives inside that shell - so the toolbar scrolls away with the body, which is worse than no cap at all. Scrolling the body alone would mean reaching into the component's internal DOM structure from product code.

How images get in

Three entry points, all going through the same `onUploadImage` (receives a File, returns a URL):

The last row deserves a note: body text copied from Word, Excel, or some web pages carries its images inlined as base64 in the HTML, with no corresponding file entry on the clipboard - so it is a different path from "pasting a screenshot" and the component handles the two separately. With onUploadImage the data: URL is turned back into a File and uploaded; without it the whole <img> is removed by the sanitizer: losing one image beats writing several megabytes of base64 into your database column.

When an upload throws, that image is not inserted and the component shows no UI of its own - the message is yours to write, since only you know what to say (quota exceeded? unsupported format? retry?). When several images are uploaded at once, one failure does not interrupt the rest.

Legacy HTML compatibility

The editor schema decides which tags survive, and it decides at load time. The table below is the "open, edit nothing, read the HTML back" contract; check your legacy samples against it before going live.

Two entry points, chosen by which side does the translating:

• The `legacyHtml` prop covers all three tiers. imgStyle and the font-family half of font are only available here: an attribute that is not in the schema is gone the moment the content is parsed, so no pure function can bring it back. While it is on, the matching extensions ignore toolbar trimming, because nobody should have to enable a color picker they do not want just to stop losing red text.
• The `normalizeLegacyHtml(html)` pure function covers the font and align tiers only, both of which are pre-parse markup translation. Use it to convert before feeding the editor, to clean a table in bulk, to write a migration script, or to share one mapping with another editor.

normalizeLegacyHtml needs DOMParser, so under plain Node you have to supply one (jsdom or linkedom); without it the input is returned unchanged rather than throwing. It translates, it does not disinfect: sanitizing still belongs to sanitizePastedHtml and to your server.

Usage guidelines

• The editor schema decides which tags survive, and it decides at load time. A tag outside the extension set (<iframe>, <video>, or a custom tag) is dropped the moment the content opens, so saving it back loses data. Not touching the content does not protect it. Add the matching node through extensions before going live with legacy content.
• For the same reason, trimming `toolbar` does more than remove buttons: dropping "table" also drops the table extension, so a legacy <table> disappears. "color", "fontSize", and "backgroundColor" back <span style="color|font-size|background-color">, and "align" backs style="text-align". Confirm the legacy content does not use that formatting before trimming.
• Before shipping, run a batch of real legacy content through "open, edit nothing, read `getHTML`" and diff it. This matters more than any unit test, because what gets lost is years of layout work. One trap while diffing: reading innerHTML off .ProseMirror adds a <br class="ProseMirror-trailingBreak"> that never reaches getHTML; leave it in and every <br> count looks doubled.
• legacyHtml preserves formatting, not structure: <section> is still flattened into <p>, only the alignment that hung on it is pushed down to the child block. Multi-column or card layouts built out of nested <section> elements are not recoverable this way; those need your own nodes through extensions.
• A centering wrapper around a lone image cannot be preserved. In <section style="text-align:center"><img></section> the image is a block node, so wrapping it in a <p> only makes ProseMirror lift it out and leave an empty paragraph behind. That shape is deliberately left alone. Center images with front-end styling (img { display:block; margin:0 auto }) rather than through the stored string.
• While legacyHtml is on, none of the removal rules relax (class, on*, <style>, and javascript: are still stripped); the inline style allowlist merely gains font-family and max-width. Values from <font color> go through a shape allowlist (named color, #hex, rgb()) so they cannot smuggle in a second declaration, because body content is a user-writable field.
• Neither swatch picker offers a `var(--…)` color. The body text is stored in your database and rendered elsewhere (v-html, a mini-program rich-text, an email), where the library CSS variables do not exist: color: var(--color-foreground) resolves to nothing there and silently falls back to the inherited color, which means an editor-only style was written into permanent content. "Default color" and "No highlight" therefore run unsetColor() / unsetBackgroundColor() - they remove the declaration rather than writing some "default" color.
• Images are never inlined as base64, and that now holds on the paste path too (it did not before 0.36.0 - see #213: pasting from Word wrote the base64 straight into the column). Transport concerns - auth headers, direct upload, progress, retries - stay with the consumer.
• `blob:` and `file:` image URLs are stripped by the paste sanitizer. The first is valid only for the lifetime of the current page and the second only on that one machine, so storing either leaves a broken image the next time the content is opened - and unlike base64 the column size looks perfectly normal, which makes it harder to notice.
• Paste sanitizing cleans structure and attributes only; it is not full XSS disinfection. Escaping and filtering still have to happen server-side when rendering to the front end, because rich text is a user-writable field and a client-side allowlist is not a security boundary.
• While controlled, the component calls setContent only when the incoming string differs from the last emitted one. Passing HTML that is semantically identical but textually different on every render (for example after your own formatting pass) resets the caret repeatedly; feed back exactly the string onChange gave you.
• A `maxRows` smaller than `minRows` does nothing at all: min-height beats max-height in CSS, so the content area still expands to minRows and never scrolls. There is no way to tell that from looking at it, so the component names it in development.
• With a cap in place the content area becomes a scroll container, which also promotes the other axis from visible to auto: legacy <img> or <table> elements carrying hard widths get a horizontal scrollbar inside the body instead of bursting out of the shell.
• Do not switch a field back and forth between this component and MarkdownEditor: their value contracts differ, and each switch is another lossy conversion.

Related

MarkdownEditor · Textarea · Field · Upload · Prose