FieldsRichtext and elements

Richtext and elements

Formatted text stored as structured data, the toolset that decides what editors may put in it, and the elements they can insert between the paragraphs.

View as Markdown

The field

f.richtext() shows a text editor and stores a document, never HTML. Render it with RichText.

components/sections/ImageText.schema.ts
    text: f.richtext({ toolset: smoodly.toolset({ marks: ["bold", "italic", "link"] }) }),

RichText comes from smoodly/astro/components:

src/sections/imageText.astro
---
import { Image, RichText, Section } from "smoodly/astro/components";
// …
---
// …
      <div class="prose" {...m.field("text")}><RichText doc={text} /></div>

RichText renders a fragment with no wrapper, so the element and class around it are yours. An empty document counts as missing, so a required richtext field must hold some text before publish. In the canvas, a marked richtext field edits in place with a floating toolbar.

Toolsets

A toolset is what a richtext field offers: which formatting, which block types, which elements. Without one, a field gets bold, italic and links, headings two to four, both lists and blockquotes. Heading one is left out because the section or page owns the page's first heading.

smoodly.toolset() builds one from three lists:

marksbold, italic, link.
nodesh1 to h6, bulletList, orderedList, blockquote, image and table. image adds pictures from the media library, with a caption; table adds a plain grid of text (below).
elementsRegistered elements, by value.

The starter keeps its toolsets in one file and imports them by value where a field needs them:

smoodly/toolsets.ts
import { smoodly } from "smoodly";
import { calloutSchema } from "../components/elements/Callout.schema";
import { ctaSchema } from "../components/elements/Cta.schema";

export const article = smoodly.toolset({
  marks: ["bold", "italic", "link"],
  nodes: ["h2", "h3", "h4", "bulletList", "orderedList", "blockquote", "image", "table"],
  elements: [calloutSchema, ctaSchema],
});

A toolset limits what editors can create, not what the document may hold. Tightening one later leaves existing content as it is, so nothing is rewritten behind an editor's back.

Tables

With table in a toolset, editors insert a table with the Table button in the toolbar or by typing /. It's a plain grid for pricing tables and comparisons: the first row is a header row by default, the first column can be one too, and each cell holds text with the field's bold, italic and links. Tab moves to the next cell, and Tab in the last cell adds a row. Inside a table, the same Table button opens a menu that adds and deletes rows and columns. Cells don't merge and carry no colour or width: those are your stylesheet's. A cell pasted with an alignment keeps it, rendered as style="text-align:…" (left, center or right). A table pasted from a spreadsheet or a document arrives as a grid; in a field without table, it arrives as its text.

RichText renders it as semantic markup with no wrapper:

<table>
  <thead><tr><th scope="col">Plan</th><th scope="col">Pro</th></tr></thead>
  <tbody><tr><th scope="row">Storage</th><td>100 GB</td></tr></tbody>
</table>

A cell with one paragraph renders its text directly, without a <p>. Style header cells with th, not thead th: while editing, the admin draws every row in one body, so th is what both have. A wide table scrolls sideways on a phone with one line:

.prose table { display: block; overflow-x: auto; }

Rendering with elements and images

The package's RichText knows your elements by file name and renders body images through Astro's image service, so there is nothing to bind. Links keep only safe targets: http, https, mailto, tel and site-relative paths.

Elements

An element is a small component editors insert between paragraphs, from the + button on the toolbar or by typing /. It is defined like a section, with contexts saying where it may go:

components/elements/Callout.schema.ts
export const calloutSchema = smoodly.schema.element({
  name: "callout",
  title: "Callout",
  icon: "!",
  description: "A highlighted note inside the text.",
  contexts: ["richtext"],
  fields: {
    title: f.text().max(80),
    body: f.richtext({ toolset: smoodly.toolset({ marks: ["bold", "italic", "link"] }) }),
  },
  settings: {
    tone: f.select([{ value: "info", label: "Info" }, { value: "success", label: "Success" }, { value: "warning", label: "Warning" }]).default("info"),
  },
  // …
});

An element's view is src/elements/<name>.astro, named after the schema:

src/elements/callout.astro
---
// …
const { title, body, settings } = Astro.props;
---
<aside class="callout" data-tone={settings.tone}>
  <strong class="callout__title">{title}</strong>
  <div class="callout__body"><RichText doc={body} /></div>
</aside>

A link an editor types in an element goes through safeHref from smoodly, as in the starter's cta.astro.

An element renders with no wrapper of Smoodly's and has no styles or CSS box: spacing is the text column's job. It may not hold a reference. In the editor an inserted element is a card with its own fields, and its sample fills it on insert.

Register an element's schema in smoodly/elements.ts and list it in the toolsets that may insert it. A toolset that names an element the config does not register fails at startup.

The view is the file; there is nothing else to list.

Next, Link.

Edit this page on GitHubLast updated 6 Oct 2026