Rich-text field

f.richText() gives an editor formatted prose: headings, bold, links, lists, tables, images. By default it stores a structured TipTap document in a jsonb column, renders a full WYSIWYG editor in the admin form, and adds JSON-aware filter operators (contains, isEmpty, …) you can use in a where clause. Switch to markdown mode and the same editor saves a plain markdown string instead.

Prerequisites: read Fields first, this page covers only the richText type. The f proxy, the chain-modifier model, and shared modifiers like .required() / .localized() / .label() are taught there.

What it does

• Stores structured rich text, a TipTap document ({ type: "doc", content: [...] }) in a jsonb column by default, so formatting survives round-trips losslessly.
• Renders a WYSIWYG editor, the admin form shows a full TipTap editor (toolbar / bubble menu / slash commands, headings, marks, links, images, tables).
• Switches to markdown, pass { mode: "markdown" } to store a plain markdown string in a text column instead of JSON.
• Filters on content, both modes expose contains (full-text search inside the document), isEmpty / isNotEmpty, and isNull / isNotNull on the where clause.
• Localizes per locale, chain .localized() to keep a separate document per locale (a shared modifier).

Quick start

Use f.richText() inside a .fields() callback. It takes no required argument (an optional { mode } object is the only one, see Constructor argument), chain the common modifiers to refine it.

import { collection } from "#questpie/factories";

export const posts = collection("posts").fields(({ f }) => ({
  title: f.text(255).required(),
  content: f.richText().label("Content").required(),
}));

That gives posts a content column typed as a TipTapDocument, required on insert, editable through the rich-text editor in the admin form, and queryable with the content operators below, no schema or migration written by hand.

Example → inferred type

A richText field contributes a TipTapDocument to the generated row type (json mode), or a string (markdown mode). .required() makes it non-null:

type Post = typeof posts.$infer.select;
//   ^? { id: string; title: string; content: TipTapDocument; ... }

A stored value is the TipTap JSON tree:

{
  "type": "doc",
  "content": [
    { "type": "heading", "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Hello" }] },
    { "type": "paragraph",
      "content": [
        { "type": "text", "text": "A " },
        { "type": "text", "marks": [{ "type": "bold" }], "text": "formatted" },
        { "type": "text", "text": " paragraph." }
      ] }
  ]
}

TipTapDocument and TipTapNode are exported types, see TypeScript.

Constructor argument

f.richText() has two call signatures. The only option is the storage mode.

mode defaults to "json". In json mode the derived Zod schema validates the { type: "doc", content?: TipTapNode[] } shape recursively; in markdown mode it is a plain z.string(). The chosen mode is recorded on the field metadata as outputMode, which the editor reads to decide whether to emit JSON or a markdown string.

Chained methods

richText adds no type-specific chained methods, its field-type definition declares only the state factory, no extra methods. You configure it entirely through the shared modifiers every field has.

The ones you'll reach for most:

collection("articles").fields(({ f }) => ({
  body: f.richText().label("Body").required().localized(),
  notes: f.richText({ mode: "markdown" }).label("Internal notes"),
}));

Filtering, operators

richText ships a small, content-aware operator set. The operators are the same names in both modes, but the implementation differs: json mode searches the text inside the JSON tree; markdown mode runs ILIKE on the text column.

// Posts whose body mentions "changelog", excluding empty drafts
const { docs } = await app.collections.posts.find({
  where: {
    content: { contains: "changelog", isNotEmpty: true },
  },
});

For the full query language, combining field filters with AND / OR / NOT, pagination, and orderBy, see the querying reference (the canonical home of the query language).

When to use it

• f.richText() (json), editor-authored formatted prose where you keep the structure: article bodies, page copy, descriptions with headings/links/images. This is the default and the right choice for almost all rich content.
• f.richText({ mode: "markdown" }), when the body must round-trip as portable markdown text (external rendering, migration, plain-text storage). You trade the structured JSON for a string.
• Need stackable, reorderable, nested content sections instead of one prose blob? That's f.blocks(), a page-builder field, not a single editor.
• Just a plain multi-line string with no formatting? Use f.textarea().

Configuring the editor (.admin())

The admin renders f.richText() with a TipTap editor whose toolbar and feature set are configurable through the field's .admin() config. You can pick a preset ("minimal" | "simple" | "standard" | "advanced"), toggle individual features (headings, links, images, tables, slash commands, character count, …), or enable image uploads to a collection.

content: f.richText().label("Content").admin({
  preset: "standard",
  features: { table: false, image: true },
  showCharacterCount: true,
  maxCharacters: 5000,
}),

TypeScript

A richText field contributes a TipTapDocument (json) or string (markdown) to the generated row, insert, and where types, no annotation needed. The document and node types are exported from @questpie/admin/fields:

import type { TipTapDocument, TipTapNode } from "@questpie/admin/fields";

type Post = typeof posts.$infer.select;
//   ^? { ...; content: TipTapDocument }

Also public from @questpie/admin/fields: richText, richTextFieldType, RichTextFieldState, RichTextFeature, and the augmentable RichTextFieldMeta. (The RichTextMode / RichTextOptions types are internal, they back the { mode } argument but aren't re-exported from the public entry.) See Fields → inferred types for how modifiers flow into the generated types.

Related

• Fields, the f proxy, the chain-modifier model, and the shared modifiers (.required(), .localized(), .label(), .default(), …).
• Blocks, the page-builder sibling: stackable, reorderable, nested content sections instead of one prose document.
• Textarea field, a plain multi-line string with no formatting.
• Admin, the module that supplies this field, and the full editor/admin-config model.