---
title: "Rich Text Field"
aliases: [rich-text-field, payload-rich-text-field]
tags: [payloadcms, fields, rich-text, lexical, content]
sources: [raw/fields__rich-text.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

The Rich Text field gives editors a WYSIWYG interface inside the Admin Panel. Content is stored as **JSON** in the database and converted to HTML (or any format) at render time.

Payload's philosophy: learn the underlying open-source editor (Lexical), not Payload-specific APIs — knowledge transfers elsewhere.

## Config Options

| Option | Required | Description |
|--------|----------|-------------|
| `name` | ✅ | DB property name |
| `label` | | Admin Panel label (string or i18n object) |
| `validate` | | Custom validation — runs on client and server |
| `saveToJWT` | | Include value in user JWT (auth collections only) |
| `hooks` | | Field-level hooks |
| `access` | | Field-level access control |
| `hidden` | | Hide from APIs and Admin Panel (still saved to DB) |
| `defaultValue` | | Default JSON content |
| `localized` | | Enable per-locale content |
| `required` | | Field must have a value |
| `admin` | | Admin Panel config (see below) |
| `editor` | | Override or customize the rich text editor |
| `custom` | | Extension point for plugin data |
| `typescriptSchema` | | Override generated TS type with JSON schema |
| `virtual` | | `true` = no DB column; or path string for virtual relationship |

## Admin Options

Inherits all base [[wiki/payloadcms/fields-overview|Field Admin Config]] options (`condition`, `disabled`, `components`, etc.).

```ts
import type { Field } from 'payload'

export const MyRichTextField: Field = {
  name: 'content',
  type: 'richText',
  admin: {
    // standard admin options here
  },
}
```

Further customization (custom toolbar elements, nodes, features) is done via editor-specific options — see [[wiki/payloadcms/rich-text|Rich Text (Lexical) overview]].

## Storage Format

- Stored as **JSON** (not HTML string) — renderer-agnostic
- Serialise to HTML on the frontend with `@payloadcms/richtext-lexical/react` or custom serializers
- JSON structure follows Lexical's EditorState format

## Editor Customization

The `editor` option accepts a configured Lexical editor instance:

```ts
import { lexicalEditor } from '@payloadcms/richtext-lexical'

{
  name: 'content',
  type: 'richText',
  editor: lexicalEditor({
    features: ({ defaultFeatures }) => [...defaultFeatures],
  }),
}
```

Full feature list (headings, links, lists, blocks, inline code, etc.) documented in [[wiki/payloadcms/rich-text|Rich Text (Lexical)]].

## Key Takeaways

- **JSON storage** — not HTML; serialization happens at render time
- **`editor` option** unlocks full Lexical customization (features, nodes, toolbar)
- **`hidden: true`** still persists to DB, just invisible from APIs and Admin
- **`virtual: true`** skips DB column entirely — useful for computed/derived content
- **`saveToJWT`** embeds the field value in the user JWT — typically avoid for large rich text values
- **Localized** works at field level — one locale per `richText` field instance
- Underlying engine is **Lexical** (by Meta) — invest learning there, not Payload wrappers

## Sources

- `raw/fields__rich-text.md` (compiled 2026-05-15)
- https://payloadcms.com/docs/fields/rich-text
