---
url: /en/docs/fields/richtext.md
description: Create and format rich content in Sveltia CMS with the Lexical editor.
---

# RichText Field

The RichText field type provides a rich text editor that supports both Markdown and HTML content. It allows content editors to format text, add links, images, and other media, making it a versatile choice for creating rich content.

::: tip Note for Netlify/Decap CMS users

For backward compatibility with Netlify/Decap CMS, the [Markdown](/en/docs/fields/markdown) field type remains available as an alias of the RichText field type. You can use either `richtext` or `markdown` as the `widget` value in your field configuration.

:::

## User Interface

### Editor

A [Lexical](https://lexical.dev/)-based rich text editor, including headings, lists, links, images, code blocks, and more. It provides a user-friendly interface for writing and formatting content.

The built-in toolbar includes buttons for common formatting options, which can be customized using the `buttons` option. The editor also supports different modes, including a raw Markdown or HTML editing mode, which can be configured using the `modes` option. Additional editor components can be added to enhance the editing experience using the `editor_components` option.

Links are edited in a floating link editor. Placing the cursor in a link shows its URL along with buttons to edit or remove the link, and selecting text and clicking the Link button or pressing `Ctrl+K`/`Command+K` opens the editor to enter a URL for the text. Without a selection, the Link button opens a dialog to insert a link along with its text.

Local/remote images can be pasted or dropped into the editor to insert them. Note: pasting multiple images is [not supported in Firefox](https://bugzilla.mozilla.org/show_bug.cgi?id=864052).

Emoji autocomplete is enabled by default. Typing a colon followed by one or more characters, such as `:smi`, brings up a list of matching emojis, the same way it works on GitHub, Slack and other apps. Use the arrow keys to move through the list, the Enter or Tab key to insert the selected emoji, and the Escape key to dismiss the list. This can be turned off with the `use_emoji_autocomplete` option.

::: tip Paragraphs and Line Breaks

In the editor, pressing Enter inserts a new paragraph, while pressing Shift+Enter inserts a line break within the current paragraph.

:::

::: warning Breaking change from Netlify/Decap CMS

Remark plugins are not supported because Sveltia CMS uses the Lexical framework instead of Slate. The `CMS.registerRemarkPlugin` API method is a noop in Sveltia CMS.

:::

### Preview

A read-only view of the rich text content, rendered as HTML.

## Data Type

If the [`format`](#format) option is set to `markdown` (default), the value will be a Markdown string. See the [Data Output](/en/docs/data-output#markdown-syntax) documentation for details on the Markdown syntax used by Lexical. If it is set to `html`, the value will be an HTML string.

If the `required` option is set to `false` and the field is left empty, the value will be an empty string.

When using the Markdown format, you need to parse the Markdown string using a Markdown parser in your framework to convert it to HTML for rendering on your website. Some frameworks have built-in support for Markdown, while others may require additional libraries. Please refer to your framework’s documentation on how to handle Markdown content. See also the [how-to](/en/docs/how-tos#rendering-soft-line-breaks-as-hard-line-breaks-in-markdown) for advice on handling line breaks in Markdown.

When using the HTML format, the value can be rendered on your website as is. Make sure to sanitize it first if untrusted users can edit the content.

::: info Future Plans

We plan to add features specific to HTML content in future releases, including text alignment, link targets, and more.

:::

## Data Validation

* If the `required` option is set to `true`, the rich text content must not be an empty string.
* If the `pattern` option is provided, the rich text content must match the specified regular expression pattern.

## Options

In addition to the [common field options](/en/docs/fields#common-options), the Markdown field supports the following options:

### Required Options

#### `widget`

* **Type**: `string`
* **Default**: `string`

Must be set to `richtext`.

### Optional Options

::: warning Breaking changes from Netlify/Decap CMS

Sveltia CMS has changed the default value of the `sanitize_preview` option to `true` for improved security. In Netlify CMS and Decap CMS prior to 3.13.0, the default is `false`, which may expose users to XSS vulnerabilities.

Also, Sveltia CMS does not support the deprecated camelCase `editorComponents` option. Use `editor_components` instead.

:::

#### `format`

* **Type**: `string`
* **Default**: `markdown`

Specifies the data format of the content. Possible values are `markdown` and `html`. This option is not available for the [Markdown](/en/docs/fields/markdown) field type, which always saves Markdown.

With the `html` format, the editor works as follows:

* The `raw` mode shows the HTML source with syntax highlighting. The formatting buttons and editor components are hidden in this mode, as they insert Markdown.
* Only the [editor components](#editor-components) that support HTML are available. The built-in `code-block` and `image` components do, so images can be inserted, pasted and dropped as usual, while a [custom component](/en/docs/api/editor-components#supporting-html) needs the `htmlSelector`, `fromBlockHTML` and `toBlockHTML` properties.
* HTML containing an element the rich text editor cannot handle, such as `<video>` without a component for it, can only be edited in the `raw` mode.
* An existing value is kept as is until the content is changed in the rich text mode. Then the editor writes HTML in its own style, such as `<strong>` for `<b>`, and attributes it doesn’t use, such as `class`, are dropped.

#### `default`

* **Type**: `string`
* **Default**: `""`

The default content for the field, written in Markdown or HTML depending on the [`format`](#format) option.

#### `minimal`

* **Type**: `boolean`
* **Default**: `false`

Whether to limit the editor height. When set to `true`, the editor height is limited to 240 pixels and a scrollbar appears when the content exceeds the height.

#### `modes`

* **Type**: `array`
* **Default**: `[rich_text, raw]`

The modes available in the editor. Possible values are `rich_text` and `raw`. The `raw` mode allows users to edit the raw Markdown or HTML text.

The following configurations are possible:

* Default modes: `[rich_text, raw]`
* Turn on raw mode by default: `[raw, rich_text]`
* Rich text only: `[rich_text]`
* Raw mode only: `[raw]`

If multiple modes are enabled, the first one is selected initially, and users can switch between them using a mode selector in the editor toolbar.

The `raw` mode comes with syntax highlighting for Markdown, including the code in fenced code blocks, while keeping the Markdown syntax characters visible. The toolbar buttons and editor components also work in this mode, inserting Markdown into the text. See the [`buttons`](#buttons) and [`editor_components`](#editor-components) options below for details. With the `html` [format](#format), the `raw` mode shows the HTML source with syntax highlighting instead.

#### `buttons`

* **Type**: `array`
* **Default**: all available buttons (see below)

The button names to display in the editor toolbar.

The following `buttons` are available in the rich text editor toolbar:

* Inline formatting: `bold`, `italic`, `strikethrough`, `code`, `link`
* Block types: `heading-one`, `heading-two`, `heading-three`, `heading-four`, `heading-five`, `heading-six`, `bulleted-list`, `numbered-list`, `quote`

By default, all buttons are enabled. You can customize the toolbar by specifying the desired buttons in the `buttons` option.

::: tip Note for Netlify/Decap CMS users

Unlike Netlify/Decap CMS, all the block type buttons are available under the block type selector in Sveltia CMS. Users can select the block type from a dropdown menu rather than having separate buttons for each block type.

:::

In `raw` mode, the buttons insert Markdown instead:

* The inline formatting buttons wrap the selected text with the corresponding Markdown syntax, such as `**` for bold, or remove it if the text is already formatted. The `Ctrl+B`/`Command+B` and `Ctrl+I`/`Command+I` keyboard shortcuts are also available.
* The `link` button opens a dialog to insert a Markdown link, using the selected text as the link text. The `Ctrl+K`/`Command+K` keyboard shortcut is also available.
* The block type selector changes the selected lines to headings, lists, a quote or a code block, and shows the block type of the line where the cursor is.

These edits can be undone with the browser’s standard undo command, just like typing.

#### `editor_components`

* **Type**: `array`
* **Default**: `[code-block, image]` plus the names of all the registered [custom components](/en/docs/api/editor-components)

The editor component names to include in the rich text editor.

Editor components are custom blocks that can be inserted into the content. Sveltia CMS includes built-in components and also allows for custom components.

Sveltia CMS includes the following built-in editor components for the RichText field:

* `code-block`: Allows users to insert and format code blocks with syntax highlighting.
* `image`: Enables users to add images to their content, with support for uploading and selecting images from the media storage. The image can be linked or unlinked based on the `linked_images` option.

Both are enabled by default. You can disable them by omitting them from the `editor_components` option.

Editor components, including custom ones, can also be inserted in `raw` mode. Clicking a component button or menu item inserts the component’s Markdown at the cursor, like `![]()` for an image, so users can fill in the values directly in the text. This is not available with the `html` [format](#format).

With the `html` format, the built-in `image` component is saved as an `<img>` element, wrapped with an `<a>` element if it’s linked, and custom components need to [support HTML](/en/docs/api/editor-components#supporting-html) to be available.

::: tip Multiple Images

The built-in `image` component is designed for single-file selection. There is no option for selecting multiple images because there is no standard Markdown syntax for it. To enable multiple images, use a custom component to achieve the desired output, as shown in [this example](/en/docs/api/editor-components#multiple-images-with-caption).

:::

::: tip Note for Netlify/Decap CMS users

Unlike Netlify/Decap CMS, the `code-block` component in Sveltia CMS is implemented as a block type. Users can insert it using the block type selector rather than the insert button. Also, the `image` component is displayed as a separate button in the toolbar for easier access.

:::

::: info Future Plans

More built-in editor components may be added in future releases, such as `table`.

:::

Developers can create [custom editor components](/en/docs/api/editor-components) to extend the functionality of the rich text editor. Custom components can be registered globally in Sveltia CMS.

#### `allow_nested_components`

* **Type**: `boolean | 'exclude_self'`
* **Default**: `true`

Whether to allow nested rich text editor components within editor components.

* `true` (default): Allows all nested components, including nesting a component inside itself
* `false`: Disables all nested components
* `'exclude_self'`: Allows nested components but excludes the parent component itself. For example, if you have a “Note” component with a rich text field, you can insert other components inside it, but not another “Note” component. This prevents potential issues with regex pattern matching when a component is nested inside itself.

::: tip Regex Matching Considerations

When nesting a component inside itself (enabled with `allow_nested_components: true`), ensure your component’s regex `pattern` can correctly handle nested instances. Simple patterns may incorrectly match the opening tag of the parent with the closing tag of the nested child.

:::

#### `linked_images`

* **Type**: `boolean`
* **Default**: `true`

Whether to allow linking images in the editor. When set to `true`, users can add links to images. When set to `false`, images will be inserted without links.

#### `use_emoji_autocomplete`

* **Type**: `boolean`
* **Default**: `true`

Whether to enable emoji autocomplete in the editor. When set to `true`, typing a colon followed by one or more characters, such as `:smi`, brings up a list of matching emojis that can be inserted into the content. The colon must be at the beginning of a line or preceded by a space or an opening bracket, so a colon in the middle of a word, as in `12:34`, does not trigger the suggestions. This works in both the rich text and raw Markdown editing modes.

#### `use_markdown_shortcuts`

* **Type**: `boolean`
* **Default**: `true`

Whether to enable Markdown shortcuts while typing in the editor. When set to `true`, typing `-` or `*` at the start of a line creates a bulleted list, `1.` creates a numbered list, `>` creates a blockquote, and `#`, `##`, `###` create headings. Standard keyboard shortcuts such as `Ctrl/Cmd+B` for bold and `Ctrl/Cmd+I` for italic are still enabled even when this option is `false`.

#### `sanitize_preview`

* **Type**: `boolean`
* **Default**: `true`

Whether to sanitize the preview content to prevent [cross-site scripting](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/XSS) (XSS) attacks. The sanitization process uses [DOMPurify](https://github.com/cure53/DOMPurify) to remove potentially harmful HTML tags and attributes from the content before rendering the preview.

::: danger Security Risk

Setting the `sanitize_preview` option to `false` can expose your CMS to XSS vulnerabilities if untrusted users have access to the CMS, especially when using [Open Authoring](/en/docs/workflows/open). Malicious users could inject harmful scripts into the content, which would then be executed in the browsers of anyone viewing the preview.

We recommend keeping this option enabled unless disabling it fixes a broken preview and you fully trust all users of your CMS or you’re the sole user.

:::

## Global Field Defaults

You can define default options for all RichText and [Markdown](/en/docs/fields/markdown) fields globally using the `field_defaults.richtext` option at the root of your CMS configuration. This allows you to set common configurations for all RichText and Markdown fields in your CMS without having to specify them in each field definition.

The following options can be defined globally:

* `format` (RichText field type only)
* `default`
* `minimal`
* `modes`
* `buttons`
* `editor_components`
* `allow_nested_components`
* `linked_images`
* `use_emoji_autocomplete`
* `use_markdown_shortcuts`
* `sanitize_preview`

The following example configures all RichText and Markdown fields to use `minimal: true`, disables Markdown shortcuts, and enables only the `bold`, `italic`, and `link` buttons by default.

::: code-group

```yaml [YAML]
field_defaults:
  richtext:
    minimal: true
    use_markdown_shortcuts: false
    buttons: [bold, italic, link]
```

```toml [TOML]
[field_defaults.richtext]
minimal = true
use_markdown_shortcuts = false
buttons = ["bold", "italic", "link"]
```

```json [JSON]
{
  "field_defaults": {
    "richtext": {
      "minimal": true,
      "use_markdown_shortcuts": false,
      "buttons": ["bold", "italic", "link"]
    }
  }
}
```

```js [JavaScript]
{
  field_defaults: {
    richtext: {
      minimal: true,
      use_markdown_shortcuts: false,
      buttons: ["bold", "italic", "link"],
    },
  },
}
```

:::

## Examples

### Standard Markdown Field

This example shows a basic Markdown editor with default settings.

::: code-group

```yaml [YAML]
- name: body
  label: Body
  widget: richtext
```

```toml [TOML]
[[fields]]
name = "body"
label = "Body"
widget = "richtext"
```

```json [JSON]
{
  "name": "body",
  "label": "Body",
  "widget": "richtext"
}
```

```js [JavaScript]
{
  name: "body",
  label: "Body",
  widget: "richtext",
}
```

:::

### Standard HTML Field

This example shows a rich text editor that saves content in HTML format.

::: code-group

```yaml [YAML]
- name: body
  label: Body
  widget: richtext
  format: html
```

```toml [TOML]
[[fields]]
name = "body"
label = "Body"
widget = "richtext"
format = "html"
```

```json [JSON]
{
  "name": "body",
  "label": "Body",
  "widget": "richtext",
  "format": "html"
}
```

```js [JavaScript]
{
  name: "body",
  label: "Body",
  widget: "richtext",
  format: "html",
}
```

:::

### Basic Markdown Field with Limited Buttons

This example shows a minimal Markdown editor with only bold, italic, and link buttons.

::: code-group

```yaml [YAML]
- name: content
  label: Content
  widget: richtext
  default: To get started, write your **Markdown** content here.
  minimal: true
  buttons: [bold, italic, link]
```

```toml [TOML]
[[fields]]
name = "content"
label = "Content"
widget = "richtext"
default = "To get started, write your **Markdown** content here."
minimal = true
buttons = ["bold", "italic", "link"]
```

```json [JSON]
{
  "name": "content",
  "label": "Content",
  "widget": "richtext",
  "default": "To get started, write your **Markdown** content here.",
  "minimal": true,
  "buttons": ["bold", "italic", "link"]
}
```

```js [JavaScript]
{
  name: "content",
  label: "Content",
  widget: "richtext",
  default: "To get started, write your **Markdown** content here.",
  minimal: true,
  buttons: ["bold", "italic", "link"],
}
```

:::

### Disabling Code Block Component

This example shows how to disable the `code-block` editor component.

::: code-group

```yaml [YAML]
- name: content
  label: Content
  widget: richtext
  editor_components: [image]
```

```toml [TOML]
[[fields]]
name = "content"
label = "Content"
widget = "richtext"
editor_components = ["image"]
```

```json [JSON]
{
  "name": "content",
  "label": "Content",
  "widget": "richtext",
  "editor_components": ["image"]
}
```

```js [JavaScript]
{
  name: "content",
  label: "Content",
  widget: "richtext",
  editor_components: ["image"],
}
```

:::