# 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.

## The field

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

File: `components/sections/ImageText.schema.ts`

```ts
    text: f.richtext({ toolset: smoodly.toolset({ marks: ["bold", "italic", "link"] }) }),
```

**Astro**

`RichText` comes from `smoodly/astro/components`:

File: `src/sections/imageText.astro`

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

**Next.js**

`RichText` comes from the site's bound renderer, below:

File: `components/sections/ImageText.tsx`

```tsx
import { RichText } from "@/smoodly/richtext";
// …
      <div className="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:

| Name | Description |
| --- | --- |
| `marks` | bold, italic, link. |
| `nodes` | h1 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). |
| `elements` | Registered elements, by value. |

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

File: `smoodly/toolsets.ts`

```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:

```html
<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:

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

## Rendering with elements and images

**Astro**

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.

**Next.js**

The `RichText` from `smoodly/react` renders text alone. A site that embeds elements or images binds its own renderer once, and imports it from there everywhere:

File: `smoodly/richtext.tsx`

```tsx
import { createRichText } from "smoodly/richtext";
import { Callout } from "@/components/elements/Callout";
import { Cta } from "@/components/elements/Cta";

export const RichText = createRichText({ elements: [Callout, Cta], sizes: "(min-width: 900px) 720px, 100vw" });
```

The bound renderer knows the elements a document may name and renders body images through `SmoodlyImage`, with `sizes` set to the text column's width. 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:

File: `components/elements/Callout.schema.ts`

```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"),
  },
  // …
});
```

**Astro**

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

File: `src/elements/callout.astro`

```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`.

**Next.js**

File: `components/elements/Callout.tsx`

```tsx
function CalloutView({ title, body, settings }: Props<typeof calloutSchema>) {
  return (
    <aside className="callout" data-tone={settings.tone}>
      <strong className="callout__title">{title}</strong>
      <div className="callout__body"><RichText doc={body} /></div>
    </aside>
  );
}

export const Callout = smoodly.element(calloutSchema, CalloutView);
```

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.

**Astro**

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

**Next.js**

Add its component to `smoodly/views.ts` and `smoodly/richtext.tsx` as well.

Next, [Link](https://smoodly.io/docs/fields/link.md).
