Skip to content

Rich text field

A short text with a few inline tags, edited with a toolbar and sanitized by the server on save.

<div data-mount="title"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/rich-text-field.css";
import { decodeEntities, parseRichText, serializeRichText } from "capsomer/behavior/rich-text-field";

Usage

import { RichTextField } from "capsomer/react/rich-text-field";

<RichTextField name="title" label="Title" tags={["em"]} initialHTML={abstract.title} />
<RichTextField name="body" label="Abstract body" tags={["em", "sup", "sub"]} lines="multi" wordCount onValueChange={setBody} />
// On the server, on every save
import { sanitizeRichText, isEmptyRichText, richTextPlain, richTextWords } from "capsomer/behavior/rich-text-field";

const title = sanitizeRichText(form.get("title"), ["em"]);
<div class="cap-field cap-rich-text">
  <span class="cap-field-label" id="…-label">Title</span>
  <div class="cap-toolbar cap-rich-text-bar" role="toolbar" aria-label="Formatting" aria-controls="…-box">
    <button type="button" class="cap-btn" data-size="sm" aria-pressed="false" aria-label="Italic" aria-keyshortcuts="Control+I Meta+I">…</button>
  </div>
  <div class="cap-input cap-rich-text-box" id="…-box" data-lines="single" role="textbox" aria-labelledby="…-label" contenteditable tabindex="0"></div>
  <input type="hidden" name="title" value="…" />
</div>

Examples

A body: italic, superscript and subscript, with a word count

<div data-mount="body"></div>

With help, required

<div data-mount="help"></div>

Invalid

<div data-mount="error"></div>

Every tag a field may allow

<div data-mount="all"></div>

API reference

RichTextField

PropTypeRequiredDoes
namestringYesThe form field's name: a hidden input carries the sanitized value.
labelReactNodeYes
tagsreadonly RichTextTag[]YesThe inline tags this field allows, in toolbar order. Italic only for a title.
initialHTMLstringThe stored value; sanitized again before it is shown.
helpReactNodeHelp, between the label and the field, read as its description.
errorReactNodeWhat is wrong and what to do; marks the field invalid.
requiredboolean
lines"single" | "multi""multi" wraps over several lines and starts taller (an abstract's body); "single" is one line's height (a title). Enter never adds a line break: the value holds inline text only.
wordCountbooleanA live word count under the field.
describedBystringAnother description's id (a limit the page states).
onValueChange(value: string) => voidEvery change, with the sanitized value.

Functions

FunctionSignatureDoes
decodeEntities(text: string): stringtext with its character references read (numeric, and the names above); an unknown name stays as written.
parseRichText(input: string, allowed: readonly ("strong" | "em" | "sup" | "sub" | "code")[]): RichTextNode[]input (HTML, or plain text with stray < and &) as a tree of plain text and the allowed tags only: any other tag is dropped and its text kept, attributes and comments are dropped, <i> reads as em and <b> as strong, and the tags are balanced (one closed out of order closes and reopens the ones inside it). Text in <script> and <style> is dropped with them.
serializeRichText(nodes: readonly RichTextNode[]): stringA tree as HTML: text escaped, tags bare.
sanitizeRichText(input: string, allowed: readonly ("strong" | "em" | "sup" | "sub" | "code")[]): stringinput kept to the allowed tags, well formed, with the ends trimmed: what a server stores.
richTextPlain(html: string): stringThe plain text of a field's value, for counting, search and plain-text email.
richTextWords(html: string): numberThe words in a field's value.
isEmptyRichText(html: string): booleanWhether a field's value has no text.
richTextNodes(doc: Document, nodes: readonly RichTextNode[]): Node[]A tree as DOM nodes, for the browser: built with createElement and text nodes, never parsed from a string.
tagsAround(node: Node | null, root: Element): ("strong" | "em" | "sup" | "sub" | "code")[]The tags that hold node inside root, innermost first.
toggleTag(root: Element, tag: "strong" | "em" | "sup" | "sub" | "code", selection: Selection | null): booleanToggles tag over the selection inside root: where the selection sits inside that tag, the tag is taken off (its text stays); otherwise the selected text is wrapped in it and stays selected. A collapsed selection, or one outside root, does nothing. Returns whether anything changed.
insertNodes(root: Element, nodes: Node[], selection: Selection | null): booleanPuts nodes where the selection is inside root, replacing what is selected, and the caret after them.

Parts and data attributes

ClassIs
.cap-rich-text-barthe root
AttributeValues
data-linesmulti

Accessibility

KeyDoes
Ctrl or Cmd + IItalic on or off (when the field allows em)
Ctrl or Cmd + BBold on or off (when it allows strong); otherwise nothing, so the browser writes no tag
Ctrl or Cmd + .Superscript on or off (sup)
Ctrl or Cmd + ,Subscript on or off (sub)
Ctrl or Cmd + ECode on or off (code)
EnterNothing: no line break
TabFrom the toolbar to the box, then on
Left, Right, Home, End in the toolbarMove between its buttons (one tab stop)
  • The box is role="textbox" named by the label (aria-labelledby), described by the help, the error and the word count, with aria-multiline for a multi-line field, aria-invalid and aria-required.
  • Each button is named in words ("Italic"), its glyph hidden, with aria-keyshortcuts and aria-pressed.
  • The word count is a polite live region.
  • Screen readers: no manual NVDA or VoiceOver run, by decision (2026-11-07); the automated browser checks and a front-end review stand in. Automated: see the site's Tests page.