richTextField

import { richTextField } from 'nextjs-cms/core/fields'

Basic usage

richTextField({ name: 'body' })

Editors get a rich-text editor with headings, lists, links, tables, and formatting. The HTML is sanitized on save and stored in a LONGTEXT column.

With every option

richTextField({
    name: 'body',
    label: 'Article body',
    required: true,
    localized: true,
    order: 4,

    placeholder: 'Start writing…',
    minLength: 200,
    maxLength: 200_000,
    sanitize: true,
    allowInlineColors: false,
    rtl: false,

    // Media: only valid with allowMedia: true
    allowMedia: true,
    allowedEmbedHosts: ['youtube.com', 'vimeo.com', 'player.acme-video.com'],
    allowImageUploads: {
        publicURL: 'https://acme.com/uploads/editor/{name}',
        size: { width: 1400, height: 1400, fit: 'inside' },
        maxFileSize: { size: 2, unit: 'mb' },
        format: 'webp',
        omitExtension: true,
    },
})

Options

Plus the common options.

Options in detail

sanitize

On by default, and you should keep it on. Before saving, the HTML is run through an allow-list sanitizer:

• Kept tags: headings h1–h6, p, br, hr, div, span, strong/b, em/i, u, s/strike, sub, sup, small, mark, code, pre, blockquote, a, img, figure, figcaption, lists (ul, ol, li, dl, dt, dd), and tables.
• Kept attributes: href, src, alt, title, target, rel, class, id, name, style, width, height, align, and data-*.
• Allowed URL schemes: http(s), mailto, tel, ftp, file, and data:image/...;base64.
• Removed: <script>, <style>, event handlers (onclick, ...), javascript: URLs, and anything not on the lists.

richTextField({ name: 'embed_code', sanitize: false }) // stored exactly as typed

allowInlineColors

Editors love coloring text; designers don't. Set it to false and the color pickers disappear from the toolbar, and the sanitizer strips color and background-color from inline styles, so pasted content can't sneak colors in either:

richTextField({ name: 'body', allowInlineColors: false })

Alignment, font size, and image sizing styles are unaffected. Only has an effect while sanitize is on.

allowMedia and allowedEmbedHosts

allowMedia: true enables the media/embed toolbar buttons and lets iframe, video, audio, source and track tags through the sanitizer.

Iframes run third-party code, so they're only kept when their src host is allowed. Hosts match exactly or as a subdomain (player.vimeo.com matches vimeo.com), never as a prefix (youtube.com.evil.example doesn't match).

// Default hosts: YouTube, Vimeo, Dailymotion, SoundCloud, Spotify, Facebook, X/Twitter
richTextField({ name: 'body', allowMedia: true })

// Only your own video platform
richTextField({
    name: 'body',
    allowMedia: true,
    allowedEmbedHosts: ['video.acme.com'],
})

allowedEmbedHosts replaces the defaults. Add them back if you still want YouTube: ['youtube.com', 'youtube-nocookie.com', 'youtu.be', 'video.acme.com'].

allowImageUploads

Without it, images pasted or dropped into the editor are stored inside the HTML as base64 data: URLs. That works, but it bloats the column and can't be cached by a CDN. With allowImageUploads, each inline image is:

1. Extracted from the HTML on save.
2. Checked against maxFileSize (the save is rejected if too large).
3. Resized to fit size and converted to format with sharp.
4. Written to <uploads>/.photos/<section>/<name>.
5. Replaced in the HTML by publicURL with {name} substituted.

richTextField({
    name: 'body',
    allowMedia: true,
    allowImageUploads: {
        // Required. {name} is replaced by the generated file name.
        publicURL: 'https://cdn.acme.com/.photos/posts/{name}',
    },
})

The three fit modes (same vocabulary as sharp):

allowImageUploads: {
    publicURL: 'https://acme.com/media/{name}',
    size: { width: 800, height: 800, fit: 'contain', background: { r: 255, g: 255, b: 255, alpha: 1 } },
    format: 'jpg', // jpeg has no transparency: use an opaque background with 'contain'
}

When an item is edited and an inline image is removed from the HTML, its file is deleted. Deleting the item deletes all its inline images.

minLength / maxLength

Measured on the stored HTML, tags included. <p>Hi</p> has length 9. Use them as coarse guards ("not empty", "not absurdly long"), not as a word count.

Examples

A blog body with embeds and uploaded images

richTextField({
    name: 'content',
    required: true,
    localized: true,
    allowMedia: true,
    allowInlineColors: false,
    allowImageUploads: {
        publicURL: `${process.env.NEXT_PUBLIC_SITE_URL}/media/.photos/posts/{name}`,
        size: { width: 1600, height: 1600, fit: 'inside' },
        maxFileSize: { size: 3, unit: 'mb' },
    },
})

A short formatted note, no media

richTextField({ name: 'announcement', maxLength: 2000, allowInlineColors: false })

Rendering on your website

The stored value is HTML. Render it with dangerouslySetInnerHTML. It was sanitized on save, but sanitizing again on output costs little if you want defense in depth:

export function Prose({ html }: { html: string }) {
    return <div className='prose' dangerouslySetInnerHTML={{ __html: html }} />
}

Storage