Appearance
Editors
Rich text, code, markdown, and syntax highlighting.
Quill 2 (default rich text)
BSD-3-Clause · lazy
html
<div class="av-field">
<label class="av-field__label" for="description">Product description</label>
<div class="av-editor"
data-av-editor
data-av-editor-toolbar="standard"
data-av-editor-placeholder="Describe the product…"
data-av-editor-input="#description"
data-av-editor-max-length="600"
style="--av-editor-min-height: 240px"></div>
<textarea class="av-textarea" id="description" name="description" rows="6"
aria-describedby="desc-count"><p>Existing content.</p></textarea>
<p class="av-field__hint" id="desc-count">
<span class="av-counter" data-av-editor-count>0</span> / 600 characters
</p>
</div>| Attribute | Default | Does |
|---|---|---|
data-av-editor-input | — | Required. Selector of the field the editor writes into |
data-av-editor-toolbar | standard | minimal, basic, standard or full |
data-av-editor-placeholder | — | Shown while the document is empty |
data-av-editor-max-length | — | Advisory count; adds is-over past the limit |
data-av-editor-readonly | inherited | true, or a readonly/disabled source field |
data-av-editor-count | — | On any element inside the field; receives the character count |
Why Quill and not TipTap
The brief was "useful, and free to use commercially". Both qualify; the cost does not.
| Licence | Packages to vendor | Toolbar | |
|---|---|---|---|
| Quill 2.0.3 | BSD-3-Clause | 1 — a webpack bundle that already contains lodash-es, parchment, quill-delta and eventemitter3 | ships one, plus a link tooltip |
| TipTap 3 | MIT | 40+ once @tiptap/pm pulls ProseMirror in | none — every button, its ARIA and its keyboard model would be ours |
BSD-3-Clause is on this repository's own allowed list beside MIT. The only clause MIT lacks is non-endorsement, which cannot bind a template. Forty vendored packages and a hand-written toolbar is a worse deal on every axis except the three letters.
The textarea is the control, and it is visible until the editor is up
This page originally showed the source field as visually-hidden. That submits a form field nobody without JavaScript can see or edit. What ships is a plain, visible .av-textarea; initEditor sets hidden on it only after new Quill() returns, and AdminVora.destroy() puts it back — along with removing the toolbar, which Quill inserts as a sibling of the container and a router would otherwise leave behind as a row of buttons wired to nothing.
A hidden
requiredfield stops the form dead, and says so only in the console. Adisplay: nonecontrol is still a candidate for constraint validation:form.checkValidity()returnsfalse, the browser refuses to submit, and it reports "An invalid form control with name='…' is not focusable" — with nothing on screen. The module moves the constraint rather than dropping it:requiredcomes off the element the browser can no longer show, and the same rule is enforced against the editor, which is focusable and is where the person needs to be sent.
An empty editor is not empty
Quill always keeps a trailing newline. getLength() reports 1 on a blank document and root.innerHTML reports <p><br></p> — a string that is truthy, non-empty, and passes a required check on the server while containing nothing at all. Both are corrected before the value leaves:
js
const length = Math.max(0, quill.getLength() - 1); // so an empty field counts 0, not 1
input.value = length ? quill.root.innerHTML : ''; // so an empty field submits nothingToolbar presets
| Preset | Contains |
|---|---|
minimal | bold, italic, link |
basic | + heading, lists |
standard | + underline, strike, blockquote, code, align, clean |
full | + colour, background, image, video |
js
const EDITOR_TOOLBARS = {
minimal: [['bold', 'italic', 'link']],
basic: [[{ header: [2, 3, false] }], ['bold', 'italic', 'link'],
[{ list: 'ordered' }, { list: 'bullet' }]],
standard:[[{ header: [2, 3, 4, false] }],
['bold', 'italic', 'underline', 'strike'],
[{ list: 'ordered' }, { list: 'bullet' }, { indent: '-1' }, { indent: '+1' }],
['blockquote', 'code-block', 'link'],
[{ align: [] }], ['clean']]
};
fullcarries neitherformulanortable, and both omissions are deliberate.formulais a KaTeX integration — a second vendor with its own fonts — and a button that throws when pressed is worse than an absent one. Quill 2'smodules/tableships with no toolbar UI and no row or column controls, so wiring the button to it produces a table nobody can edit afterwards.
Images are inserted by URL, never base64
Quill's stock image handler reads the file and embeds it as a data URI — four paragraphs above the warning on this page telling you never to do that. A static template has no upload endpoint, so the handler is rebound to ask for a URL through the same native <dialog> the confirm dialog uses. In a real application, replace it:
js
quill.getModule('toolbar').addHandler('image', () => {
const input = Object.assign(document.createElement('input'),
{ type: 'file', accept: 'image/png,image/jpeg,image/webp' });
input.onchange = async () => {
const file = input.files[0];
if (file.size > 5 * 1024 ** 2) return AdminVora.toast.error('Image must be under 5 MB');
const body = new FormData();
body.append('file', file);
const range = quill.getSelection(true);
try {
const res = await fetch('/api/uploads', { method: 'POST', body });
const { url } = await res.json();
quill.insertEmbed(range.index, 'image', url, 'user');
} catch {
AdminVora.toast.error('Upload failed');
}
};
input.click();
});A 2 MB photo becomes 2.7 MB of text in the row, and every diff, search and export downstream carries it.
Sanitisation
The value is HTML, which makes a rich text field a stored-XSS vector by construction. No client-side measure changes that — an attacker posts to your endpoint directly.
What the client does guarantee is narrower and worth stating precisely: the value is Quill's rendering of a Delta, so it contains only the formats Quill knows about. That is a constraint, not a sanitiser. The initial value goes in the same way, and the method name is misleading about which direction is safer:
js
quill.clipboard.dangerouslyPasteHTML(input.value, 'silent');dangerouslyPasteHTML runs the markup through Quill's matcher chain into a Delta and renders that, so a script, an event handler or an unknown attribute does not survive the round trip. Assigning to quill.root.innerHTML would keep all of it.
There is no
AdminVora.utils.sanitize. This page used to call one; the runtime exposesformatCurrencyand nothing else. DOMPurify is not vendored — adding it is a supply-chain decision that has not been taken, and it would not change the paragraph above.
php
// Server — the only control that counts
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.Allowed',
'p,br,strong,em,u,s,h2,h3,h4,ul,ol,li,blockquote,pre,code,a[href|title|rel],img[src|alt|width|height]');
$config->set('URI.AllowedSchemes', ['http' => true, 'https' => true, 'mailto' => true]);
$clean = (new HTMLPurifier($config))->purify($request->input('description'));Theming: the stylesheet splits in half
Only quill.core.css is vendored, and the line falls where the CSS stops being design:
| What it is | Vendored | |
|---|---|---|
quill.core.css | Mechanics — nine indent levels, the ordered-list counters, alignment, direction, the off-screen .ql-clipboard node paste depends on | Wrapped in @layer plugins |
quill.snow.css | Chrome — button sizing, SVG stroke colours, the picker dropdown, a #ccc border, a #06c active state | Not loaded: plugins/_quill.scss repaints it from tokens |
The snow theme is still used: its JavaScript builds the toolbar, the format pickers and the link tooltip. Only the painting is ours — the Tom Select pattern, and the opposite of CodeMirror, whose CSS cannot be reached from a partial at all.
The theming sweep could not see any of it until this integration.
tests/lib/theming.mjsreadbackground-color,colorand the four border colours — none of which an inline-SVG icon paints through. It also crashed on the first SVG it met, becauseclassNameon an SVG element is anSVGAnimatedStringrather than a string. It readsfillandstrokenow, and the first thing it reported was eighteen<svg>roots inheriting the initialblackinto any path Quill draws untagged.
Accessibility
Quill builds the toolbar itself and builds it bare: no labels, no role, and fourteen tab stops before the text. All three are the wrapper's job.
js
bar.setAttribute('role', 'toolbar');
bar.setAttribute('aria-label', 'Text formatting');
controls.forEach((btn, i) => { btn.tabIndex = i === 0 ? 0 : -1; }); // roving
quill.root.setAttribute('aria-multiline', 'true');
quill.root.setAttribute('aria-labelledby', label.id);The arrow keys move within the toolbar, and they are swapped under dir="rtl" — the key names a direction on screen, not an index in an array. tests/editor.mjs asserts the single tab stop, since "has a role" and "is one stop" are different questions and only the second is the one a keyboard user asks.
Hiding the proxy takes its ARIA with it
The textarea is hidden from the moment the editor mounts, which removes it from the accessibility tree — so every state and description written to it after that point is written to an element no assistive technology can reach. The required trap below is the well-known case; two more travel with it, and both were live:
js
quill.root.setAttribute('aria-invalid', over ? 'true' : 'false'); // not on the textarea
const describedBy = input.getAttribute('aria-describedby'); // the hint, and the limit
if (describedBy) quill.root.setAttribute('aria-describedby', describedBy);The character limit is written down in the hint under the field, and that hint is wired to the textarea, because the textarea is the control the page author wrote. Copy it onto the surface — not move it, because destroy() unhides the textarea and it needs its description back.
The editor announces its own writes
Assigning to .value fires no event, so a field enhanced this way changes under everything that was watching it: validation, an autosave, a readiness panel. sync() dispatches the event the browser would have:
js
if (input.value === next) return;
input.value = next;
input.dispatchEvent(new Event('input', { bubbles: true }));Silent on the first pass, deliberately. Quill re-renders the server's markup into its own normalised form, so mounting almost always changes the string — and a form carrying data-av-dirty-guard would then believe the visitor had edited something before the page finished loading, and offer to discard their changes on the first link they pressed.
CodeMirror 6 (code editing)
MIT · opt-in
html
<div class="av-field">
<label class="av-field__label" for="webhook">Webhook payload</label>
<div class="av-code-editor"
data-av-code-editor
data-av-code-editor-language="json"
data-av-code-editor-input="#webhook"
data-av-code-editor-status="#webhook-status"
style="--av-editor-min-height: 200px"></div>
<textarea class="av-input av-code-editor__source" id="webhook" name="payload" rows="8">{
"event": "order.paid"
}</textarea>
<p class="av-code-editor__footer">
<span class="av-code-editor__lang">json</span>
<span class="av-code-editor__status" id="webhook-status" role="status"></span>
</p>
</div>| Attribute | Default | Does |
|---|---|---|
data-av-code-editor-input | — | Required. Selector of the field the editor writes into on every keystroke |
data-av-code-editor-language | json | Grammar to load. Only json is vendored — see below |
data-av-code-editor-status | — | Selector of an element the module reports JSON validity into |
data-av-code-editor-line-numbers | true | false hides the gutter |
data-av-code-editor-readonly | inherited | true, or a readonly/disabled source field |
data-av-code-editor-mode | written by the module | light or dark — the live theme configuration, readable from CSS or a test |
The textarea is the control, and it is visible until the editor is up
This page originally showed the source field as visually-hidden. That submits a form field nobody without JavaScript can see or edit, which is the opposite of the graceful degradation the pattern is for. What ships is a plain, visible .av-input textarea; initCodeEditor sets hidden on it only after new EditorView() has returned, and AdminVora.destroy() puts it back. A failed import, a blocked bundle or a browser that never runs the script all leave a working form.
Vendoring: the case none of the other eight prepared us for
Every other vendor here ships either a self-contained ESM or a UMD bundle whose global the loader reads back. CodeMirror 6 ships neither. It is seventeen packages importing each other by bare specifier — import { EditorState } from '@codemirror/state' — and a browser has no node_modules to resolve that against.
| Route | Why not |
|---|---|
| Bundle it | Puts a second, divergent build in front of files the demo pages link directly |
| An import map | Seventeen entries in the <head> of every page that might one day carry an editor — a vendoring decision leaking into markup |
| Rewrite the specifier on the way in | ✅ |
tools/vendor-sync.mjs rewrites them, in the same place and for the same reason it wraps a vendored stylesheet in its cascade layer: the vendored copy is a derivation of the pinned source, the derivation is declared in the manifest (provides and rewriteImports per file), and the audit re-derives it rather than trusting what is on disk. Hand-editing a vendored file still fails npm run vendor:audit.
The load-bearing part is not the rewrite, it is the assertion after it: any specifier still unresolved when the pass finishes aborts the build. A rewrite that silently misses one produces a file that looks vendored, passes its checksum, and fails in the browser with a bare-specifier error the first time a customer opens the page. Bumping a version that gains a transitive dependency is exactly how that would happen, and it now stops at npm run vendor instead.
Two narrowings make the rewrite safe to run over a third party's source. It is anchored to a line beginning import or export, because @lezer/lr documents a grammar declaration reading @context exportName from "module" inside a doc comment — a pattern that trusted the shape of a from clause alone would rewrite prose, or fail a build over a sentence. And the body between the keyword and from excludes ; and quotes rather than using ., so a wrapped import list is matched without running past the end of its own statement.
Theming: the one vendor a plugins/ partial cannot reach
CodeMirror injects its base theme through style-mod as a plain <style> element at the top of <head>, with no @layer around it. An unlayered author declaration beats every layered one regardless of specificity or source order, so a plugins/_codemirror.scss full of .cm-scroller rules would compile, ship, and do nothing at all — the worst failure shape there is, because it reads as working CSS. !important does not rescue it either: lint-css.mjs permits that in plugins/ only on a property some vendor has itself locked, and CodeMirror locks none.
So the interior is themed through EditorView.theme(), whose generated class outranks the base theme inside that same unlayered origin. That turns out to be the better route anyway:
js
'&': { backgroundColor: 'transparent', color: 'var(--av-text-primary)' },
'.cm-gutters': { borderRight: '1px solid var(--av-border-subtle)', color: 'var(--av-text-subtle)' },
'.cm-activeLine': { backgroundColor: 'var(--av-surface-raised)' }A CodeMirror theme is a stylesheet, so var(--av-…) passes straight through it. The editor follows every preset, both modes and the density and contrast axes with no JavaScript in the render path at all — a stronger position than the getComputedStyle reads this page used to show, which freeze the values at construction. Contrast ApexCharts, which parses colours itself and has to be handed hex.
The compartment stays, and it holds exactly one thing that is not a colour. CodeMirror's
darkflag decides which half of its own&light/&darkbase rules apply — the parts this theme does not override — and a boolean cannot be carried by a custom property. It is reconfigured onav:theme:changeandav:theme:mode: only the second fires when the OS flips under a page sitting insystemmode.
basicSetup also registers CodeMirror's own defaultHighlightStyle, which is eight hard-coded hex values. It is registered with fallback: true, so supplying a token-driven HighlightStyle replaces it rather than fighting it — and tests/code-editor.mjs fails if it ever shows through, which it does by reporting #a11, #116644 and #221199 the moment the extension is removed.
One language, and the omission is the decision
Only the JSON grammar is vendored. Every additional language is another lezer parser to copy, checksum, licence and carry, and the admin cases that actually want a code editor — a webhook payload, a config blob, a seed fixture — are JSON. languages in the loader is the extension point: a second language is a manifest entry and one row.
JavaScript, HTML, CSS, SQL, Python, Markdown and YAML are not vendored.
Choosing an editor
| Need | Use |
|---|---|
| Product descriptions, comments, articles | Quill |
| Collaborative editing, mentions, custom blocks | TipTap |
| Configuration, queries, templates | CodeMirror |
| Documentation, README-style content | Markdown editor |
| Read-only code display | Prism |
| A single-line formatted field | Plain <input> — not an editor |
Checklist
- [ ] A real form field (
<textarea>/<input>) backs the editor - [ ] Editor content sanitised client-side and server-side
- [ ] Images uploaded to storage, never base64-embedded
- [ ] Toolbar has
role="toolbar", a label, and labelled buttons - [ ] Editable region has
aria-multilineand an accessible name - [ ] Character/word limits enforced and announced
- [ ] Editor re-themes on
av:theme:change - [ ] Language grammars loaded per-language, not all at once
- [ ]
destroy()called on unmount - [ ] Paste from Word/Google Docs produces clean output (test it)
Read next: File Upload.