Rich text editor

On this page

phApp.editor() adds a rich text editor for announcements, notes and messages: bold, italic, underline, headings, lists, quotes and links. phApp.richText() shows the result safely. Both are built on Tiptap 3, and all HTML going in and out is sanitised.

Add ph-app-editor.js after ph-app.js on pages with an editor:

<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app-editor.js"></script>

Editor

A rich text editor in a formA rich text editor in a form

Figure 1: The editor with its toolbar, in a form field

<form class="ph-form">
  <div class="ph-field">
    <label class="ph-label" for="announcement">Announcement</label>
    <div id="announcement"></div>
    <p class="ph-hint">Everyone on the team sees this on the intranet home page.</p>
  </div>
</form>
const editor = phApp.editor('#announcement', {
  name: 'message',                       // adds a hidden input, so the form posts it
  placeholder: 'Write something for the team…',
  content: savedHtml,
  onChange: (html) => (saveButton.disabled = editor.isEmpty()),
});

The editor takes its accessible name from the <label for>; or set label.

OptionDefaultWhat it does
contentemptyStarting HTML (sanitised)
placeholdernoneShown while it's empty
labelthe <label for>, else "Rich text"The accessible name
toolbarsee belowThe buttons, in order, with `'
minHeight / maxHeight140px / noneThe editing area's height; it scrolls past maxHeight
editabletruefalse makes it read-only
namenoneA hidden input with this name holds the HTML, for forms
onChangenone(html, editor), on every change

It returns getHTML() ('' when empty), getText(), isEmpty(), setContent(html), setEditable(editable), focus(), destroy(), and editor, the Tiptap editor.

Toolbar

The default toolbar is:

['bold', 'italic', 'underline', '|', 'heading', 'bulletList', 'orderedList', 'blockquote', '|', 'link', '|', 'undo', 'redo']

ToolButtonShortcut (Ctrl on Windows, ⌘ on Mac)
boldBoldCtrl+B
italicItalicCtrl+I
underlineUnderlineCtrl+U
strikeStrikethroughCtrl+Shift+S
headingHeadingCtrl+Alt+2
bulletListBulleted listCtrl+Shift+8
orderedListNumbered listCtrl+Shift+7
blockquoteQuoteCtrl+Shift+B
codeCodeCtrl+E
codeBlockCode blockCtrl+Alt+C
linkLinknone
undo / redoUndo / RedoCtrl+Z / Ctrl+Shift+Z

strike, code and codeBlock aren't in the default toolbar; add them to toolbar to show them. The Link button opens a dialog to add, edit or remove a link. Addresses without a scheme get https://.

Showing rich text

Sanitised rich text in a cardSanitised rich text in a card

Figure 2: Saved HTML shown with phApp.richText()

phApp.richText('#announcement', savedHtml);

phApp.richText() sanitises the HTML and styles it with .ph-rich-text. phApp.sanitizeHtml(html) returns the sanitised string, if you need it yourself.

Sanitising keeps paragraphs, line breaks, bold, italic, underline, strikethrough, code, quotes, lists, headings 1 to 4, links and rules, and removes everything else, including scripts, styles, images and event handlers. Links open in a new tab with rel="noopener noreferrer nofollow".

Accessibility

  • The toolbar is one tab stop. Arrow keys, Home and End move between its buttons.
  • Every button has a name, and its shortcut is in the tooltip and aria-keyshortcuts.

React

import { RichTextEditor, RichTextView } from 'ph-app-kit-react/editor';

<RichTextEditor aria-label="Announcement" value={html} onChange={setHtml} placeholder="Write something for the team…" />
<RichTextView html={saved} />

Guidelines

  • Use it where formatting matters to the reader. For short notes, a plain <textarea> is better.
  • Sanitise on the server too; the kit protects the page, not your API.
  • Never put rich text into the page with innerHTML yourself; use phApp.richText().