A framework-agnostic WYSIWYG / Markdown editor, shipped as a
<km-editor>Web Component on ProseMirror.
@keenmate/web-editor is a custom element (<km-editor>) that gives you one
editable document with Markdown, HTML, and JSON as import/export formats at the
edges. It's built on ProseMirror and the shared
@keenmate/web-components-core runtime (shadow DOM, adopted styles) — the same
model as the rest of the Keenmate component line. Works in React, Vue, Svelte,
Blazor, or plain HTML.
Headline features:
- Single document model — Markdown / HTML / JSON are just the I/O lens, switchable without rebuilding the content.
- Four view modes —
edit,split(editor + live output),preview(read-only), andinline(a floating card that can anchor to a page element). - A command-driven toolbar that docks to any edge, a floating selection toolbar, a right-click context menu, and a status bar with live word/char counts.
- Plugin-assembled — links, images, tables, and code highlighting are first-party plugins; you can add your own.
- Framework-agnostic: declarative attributes for the simple case, a small imperative API for dynamic content and events.
- 🧪 Live examples — the hosted example site (basic usage, rich content, plugins, the pipeline lab, and the playground).
- 📘 Pipelines guide — how pipelines work, with diagrams.
- 📚 Examples guide — the example-site convention.
npm install @keenmate/web-editorDeclarative — just attributes:
<script type="module">
import '@keenmate/web-editor';
</script>
<link rel="stylesheet" href="@keenmate/web-editor/style.css" />
<km-editor value="# Hello" content-format="markdown" toolbar="top"></km-editor>Programmatic — dynamic content + events:
import '@keenmate/web-editor';
const editor = document.querySelector('km-editor');
editor.addEventListener('ready', () => editor.focus());
editor.addEventListener('change', (e) => {
console.log(e.detail.value, e.detail.contentFormat);
});
// …or the camelCase twin, called with the same detail:
editor.onChange = ({ value, contentFormat, controller }) => console.log(value, contentFormat);
editor.setValue('## New heading', 'markdown');
editor.value; // live content in the active `contentFormat` (the `value` attribute is only the initial content)
editor.getMarkdown(); // live content as markdown, whatever `contentFormat` is
editor.controller.runCommand('bold'); // the public facade (also on every event detail)Every attribute is also a property (e.g. el.viewMode = 'preview' ↔ view-mode), typed on
KmEditorElement (TypeScript: el.viewMode, el.customStyles, … — the EditorConfig keys).
An invalid value warns, keeps the previous one and fires input-rejected; el.x = undefined (or
removing the attribute) resets an input to its default.
| Attribute | Values | Default | Description |
|---|---|---|---|
value |
string | — | Initial content, interpreted per contentFormat (property defaultValue, like a native input). Changing it replaces the document. The live content is the value property. |
content-format |
markdown | html | json |
markdown |
The format of the one document — the lens for content I/O (the value attribute and property, the change detail). Switching re-reports the same document in the new format — it never rebuilds it, and fires no change. |
name |
string | — | Form field name: a light-DOM hidden <input name="…"> carries the live content (in content-format) and submits with the <form> — see Forms. |
view-mode |
edit | split | preview | inline |
edit |
Presentation. preview forces read-only. inline renders a floating card (see anchor). Assigning is silent; setViewMode() and the toolbar's Edit / Split / Preview items fire view-mode-change. |
readonly |
boolean | false |
Read-only (isReadonly): the content can't change, the editing toolbar groups are hidden (the view-mode group stays), but it stays focusable (in the tab order) / selectable / copyable (Ctrl/⌘+A selects the document). view-mode="preview" also forces this on. Reflects. |
disabled |
boolean | false |
Disabled (isDisabled): no interaction — not editable, focusable or selectable (the surface is inert). An ancestor <fieldset disabled> disables it too. Reflects, like a native control. |
toolbar |
top | bottom | start | end | none |
top |
Which edge the command toolbar docks to (none hides it). Its last group, at the far end, is the view-mode radio group — view-edit / view-split / view-preview (Edit / Split / Preview; toggled = the active mode; not shown in inline). While read-only / preview only that group shows; disabled hides the toolbar. The selection toolbar and context menu are always available while editing. |
statusbar |
none | top | bottom | both |
none |
A dedicated strip of live indicators (word/char count, plugin items). both splits items across two strips. |
anchor |
CSS selector | — | For view-mode="inline" only: the page element the floating card tracks. |
labels |
JSON object | English | UI strings — see Labels. Also a property (object). |
menu-presentation |
auto | floating | sheet | drawer |
auto |
How the right-click menu opens (core /menu): auto = a bottom sheet on a phone, floating otherwise; drawer slides in from menu-side. Read at every open; responsive rules can set it (menuPresentation). |
menu-side |
start | end |
end |
The edge a drawer menu slides in from. |
custom-styles |
CSS string | — | CSS injected into the shadow root (customStyles), after the page-wide layer — see Theming. Raw CSS: never untrusted input. |
Property-only inputs:
| Property | Type | Description |
|---|---|---|
getValueFormatCallback |
(ctx) => string |
Formats the value written into the hidden form input (e.g. sanitizing); ctx = { value, contentFormat } + controller / element. Affects only the submitted value — see Forms. |
beforeActionCallback |
(detail) => false | void | Promise<…> |
Runs first on every toolbar / selection-toolbar / context-menu activation; false cancels (no onClick, no action event, no command). |
renderLoadingCallback |
(ctx) => void | cleanup |
Draws the pending loader (shown while a deferred pipeline's work — e.g. a cloud-image upload — outlives its threshold; not while a dialog waits for the user) instead of the default spinner; ctx = { component, context: 'pipeline', containerElement, element, label }. Beats the page-wide window.components.renderLoadingCallback. See Theming. |
interactionHost |
{ request(ctx) } |
The modal bridge interactive pipeline stages call (ctx = request + signal + controller / element). Default: window.confirm. Survives engine rebuilds. |
getCustomStylesCallback |
(ctx) => string | null |
Computes the instance CSS (wins over customStyles); ctx = controller / element. See Theming. |
Events — bubble, not composed. Each has a camelCase twin property (onChange,
onReady, onViewModeChange, onLockChange, onValueFormatError, onAction) called with the same detail
before the DOM event. Every detail carries controller and element (non-enumerable —
JSON.stringify(detail) shows only the data).
| Event | detail |
Fires when |
|---|---|---|
change |
{ value, contentFormat } |
Content changes by the user, a plugin or setValue() (unless { isSilent: true }), serialized in the active contentFormat. Assigning value / contentFormat is silent, like a native input.value; so is a form reset (like a native form.reset()). |
ready |
the context only | The engine has mounted and is ready (once). |
view-mode-change |
{ viewMode, oldViewMode, source } |
The view mode was switched — source: 'user' (the Edit / Split / Preview toolbar items), 'api' (setViewMode() on the element or controller, incl. controller.runCommand('view-…')), 'plugin' (a plugin's setup ctx / a pipeline stage's rt.setViewMode). Assigning viewMode / view-mode is silent. |
lock-change |
{ isLocked } |
A gating pipeline (e.g. the cloud-image picker) locks / unlocks the editor. |
value-format-error |
{ error, value } |
getValueFormatCallback threw (value = the unformatted document). The field is invalid until the next successful format — see Forms. |
action |
{ action, id, item, source, sourceEvent, triggerElement, dataset, state } |
A toolbar / selection-toolbar / context-menu item was activated (source: toolbar | selection-toolbar | context-menu). After the item's onClick and the command (a notification after the fact; state is the snapshot from activation). Keyboard shortcuts don't fire it. |
Methods & properties:
| Member | Returns | Description |
|---|---|---|
value |
string |
The live content, serialized in the active contentFormat. Assigning replaces the document silently — no change, like a native input.value; the hidden form input is synced (the value attribute is not written). |
getMarkdown() / getHTML() |
string |
Live content in that format. |
getJSON() |
unknown |
Live content as the ProseMirror JSON document. |
setValue(value, format?, options?) |
void |
Replace the document from value, parsed in format (default: the active contentFormat). Fires change unless options.isSilent ({ isSilent: true }); also on el.controller. |
setViewMode(mode, options?) |
void |
Switch the view mode; fires view-mode-change (source: 'api') unless options.isSilent. No-op when already active; an invalid mode warns and is ignored. Also on el.controller. |
focus() |
void |
Focus the editing surface. |
isReady / whenReady() |
boolean / Promise<void> |
Core: the first build is live (ready attribute, :state(ready), ready event). |
shouldDefer / release() |
boolean / void |
Core: hold the first build (attribute defer) until release() / removing defer. |
plugins |
EditorPlugin[] |
The active plugin set — assign to compose with defaultPlugins() (rebuilds, preserving content). |
controller |
EditorController |
The public facade (also detail.controller / ctx.controller): value (read-only), getHTML / getMarkdown / getJSON, setValue, setViewMode, focus, runCommand(name | ProseMirror command), isCommandToggled(name), isCommandEnabled(name). Programmatic — no action event. |
destroy() |
void |
Core: final teardown of the engine and shadow layout (idempotent; isDestroyed). The element stays inert — create a new one instead of re-inserting it. |
The internal engine is not exposed on the element; EditorEngine is exported for
standalone (headless) use.
Every UI string goes through one labels object — partial (unset keys stay English),
{name} placeholders, applied live (no rebuild). '' means deliberately empty (renders
nothing); a missing key falls back to English. Every editor label is inserted as text
(none is HTML), so there are no HTML-injection labels:
<km-editor labels='{"bold":"Tučně","insertLink":"Vložit odkaz","linkUrlPrompt":"Adresa odkazu:","words":"Slova: {count}"}'></km-editor>| Key | English default |
|---|---|
<commandKey> — the command id camel-cased (bold, insertLink, insertTable, bulletList, undo, a plugin's imageBrowserPick, …) |
the command's own text (Bold, Insert link, …) — item text, menu label, button aria-label |
<commandKey>Tooltip |
the command's tooltip, else <text> (<shortcut>) |
<groupId>Group — formatGroup, blockGroup, listGroup, insertGroup, historyGroup, viewGroup, linkGroup, imageGroup, tableGroup, imageBrowserGroup |
toolbar group accessible names (Format, Block, Lists, …) |
placeholder |
'' (off) — shown (as text) while the document is empty |
words / chars |
Words: {count} / Chars: {count} (status bar) |
linkUrlPrompt |
Enter link URL: |
imageUrlPrompt / imageAltPrompt |
Enter image URL: / Enter alt text (optional): |
codeLanguagePrompt / codeLanguageChangePrompt |
Enter language ({languages}): / Change language ({languages}): |
cloudImage, cloudImageTooltip, insertCloudImage, cloudImagePickerTitle, cloudImagePickerMessage |
cloud-image plugin texts |
back / close |
Back / Close — the context menu's submenu back button and close button when it opens as a sheet / drawer (menu-presentation) |
loading |
aria-label of the pending loader ("Loading…") |
valueFormatError |
validation message while getValueFormatCallback throws ("The value could not be formatted.") |
Plugin code resolves strings with label(key, params?, fallback?) — on the plugin
builder ctx (commands: ({ schema, label }) => …), on every callback ctx (ctx.label)
and on pipeline stages (rt.label). DEFAULT_LABELS and labelKey() are exported.
<km-editor name="body"> inside a <form> submits the live content under body,
serialized in content-format (markdown by default). Like the suite's other form
components it uses a light-DOM hidden input (a child of the host) — not
ElementInternals.setFormValue — so there is exactly one entry. The editor starts
empty unless value is given; form.reset() restores the value attribute
(defaultValue) silently — no change, like a native control — and a disabled editor (disabled, or an ancestor
<fieldset disabled>) is left out of the submission.
<form>
<km-editor name="body" content-format="html" labels='{"placeholder":"Write your post…"}'></km-editor>
</form>To change what is submitted (e.g. sanitize the HTML), set getValueFormatCallback.
It formats only the hidden input's value: el.value and the change detail stay the
document in contentFormat. If the callback throws, the error is logged, the hidden
input gets an empty value, the host turns invalid (customError, message = label
valueFormatError) and value-format-error { error, value } fires — so the form refuses
to submit (invalid fires on the editor; <form novalidate> submits the empty value).
The next successful format clears it. The standard el.validity / validationMessage /
checkValidity() / reportValidity() and :invalid work (core).
editor.getValueFormatCallback = ({ value, contentFormat }) =>
contentFormat === 'html' ? DOMPurify.sanitize(value) : value;Tune any input per device class or window width without app-side resize code — the shared
@keenmate/web-components-core mechanism
(SPEC §6.7).
A map has two axes, each keyed mobile | tablet | desktop → partial config:
device— what the device is: a touch phone (mobile) / tablet by capability; a mouse / trackpad device isdesktopat any width.breakpoint— the window width (768 / 1024 px lines), so a narrowed desktop window ismobile.
Both apply; on the same key device wins. Own widths or combinations (device AND width,
orientation, …) go in a callback ((ctx) => partial config,
ctx = { env, deviceClass, breakpoint, element, component, config }). Either can be set at
three levels:
window.components.responsive = { device: { mobile: { toolbar: 'bottom' } } }; // page — every component
window.components['km-editor'].responsiveCallback = ({ env }) => // page — every <km-editor>
env.viewportWidth < 600 ? { toolbar: 'bottom' } : undefined;
editor.responsive = { breakpoint: { mobile: { toolbar: 'none' } } }; // this instance
// or <km-editor responsive='{"breakpoint":{"mobile":{"toolbar":"none"}}}'>Precedence (later wins, key by key): page map → page callback → per-tag map → per-tag
callback → attributes / properties set on the instance → instance map → instance
callback. So <km-editor toolbar="top"> keeps its toolbar on top whatever the page rules
say; only the instance's own rules beat it. Overrides never reflect to attributes, el.config
/ the property getters return the effective value, and a key a rule stops returning goes
back to its base value. Rules re-run when the device class / breakpoint / orientation
changes (callbacks also on every viewport-width change). Types: EditorResponsiveMap, EditorResponsiveCallback (over EditorConfig).
The component is shadow-DOM scoped, so its styles don't leak and page styles don't bleed in. Ship the stylesheet once:
<link rel="stylesheet" href="@keenmate/web-editor/style.css" />Dark mode follows the page. Every color is a --we-* variable chained to the shared
--base-* contract with light-dark() fallbacks, so the editor resolves whichever scheme its
host is in:
- No signal — the editor inherits the page's
color-scheme(html { color-scheme: light dark }follows the OS). - Page signal —
data-theme/data-bs-theme/.dark/.lighton<html>or<body>, atheme-sourcesection, or coresetThemeMode(): core mirrors it onto the host asdata-context-theme. - Per instance —
<km-editor data-theme="dark">(or"light") wins over the page.
The selection toolbar is a dark pill in both modes (the shared tooltip tokens), and code blocks
stay dark in both (the syntax highlighting is Prism's dark theme). Re-theme with --base-* on
:root (every Keenmate component follows), or --we-* on the element:
km-editor { --we-accent: #7c3aed; --we-min-height: 320px; }All variables are listed in component-variables.manifest.json
(import manifest from '@keenmate/web-editor/manifest').
Custom CSS (shadow root). Page CSS can't reach inside the shadow root; inject it instead
(core createCustomStyles()). Two layers, each a <style> in the shadow root, the instance one
last so it wins:
// every <km-editor> on the page (one file, fetched once)
window.components['km-editor'].customStyles = "@import url('/css/editor-overrides.css');";
// or computed per instance (wins over the page-wide customStyles)
window.components['km-editor'].getCustomStylesCallback = ({ element }) =>
element.classList.contains('notes') ? '.ProseMirror { font-family: Georgia, serif; }' : null;<!-- this editor only: attribute custom-styles / property customStyles, or getCustomStylesCallback(ctx) -->
<km-editor custom-styles=".ProseMirror { letter-spacing: .02em; }"></km-editor>An @imported font (@font-face) is also linked once in the document <head>, since Chromium
ignores @font-face inside a shadow root (window.components.shouldHoistImports = false turns
that off). Custom CSS is raw — never put untrusted input there.
The editor's own classes and custom properties use the we- prefix (--we-bg,
--we-border, --we-accent, …). Disabled commands fade by --we-disabled-opacity
(default var(--base-disabled-opacity, 0.65)). While a deferred pipeline outlives its threshold a
loader shows in the body's top-end corner (::part(loader), role="status", label loading): the
shared Keenmate loader, drawn from --we-loader-icon / --we-loader-rotate / --we-loader-duration
/ --we-loader-size (each chained to --base-loader-*, so one page-level change restyles every
component's loader; it slows under reduced motion). For a richer loader set renderLoadingCallback
on the element or window.components.renderLoadingCallback for the page. Apart from that spinner
the editor has no transitions or animations of its own; the right-click menu's motion follows core's --km-menu-* / --base-duration-*
(--base-duration-*: 0s turns it off page-wide). The right-click menu is the shared Keenmate menu
from @keenmate/web-components-core (.km-menu*, ::part(context-menu)); restyle it
with the --we-context-menu-* properties on the element — bg, text-color,
border, border-radius, shadow, min-width, padding, font-size,
item-padding, hover-bg, hover-color, toggled-color, shortcut-color,
danger-color, divider-color, disabled-opacity, z-index.
Each menu value resolves, highest precedence first: --we-context-menu-* (this
editor) → --km-menu-* (every Keenmate menu on the page) → --base-* (theme)
→ core's default. The --we-context-menu-* properties are unset by default, so a
page-wide --km-menu-* reaches the editor's menu:
:root { --km-menu-bg: #fffbe6; } /* every menu on the page */
km-editor.notes { --we-context-menu-bg: #eef; } /* just this editor's menu */The list of --km-menu-* variables ships in core's
@keenmate/web-components-core/component-variables.manifest.json.
The editor assembles itself from a plugin set. Links, images, tables, and code
highlighting are first-party plugins used by default; you can add your own with
definePlugin(...) and compose them with defaultPlugins():
import { definePlugin, defaultPlugins } from '@keenmate/web-editor';
// …define a plugin, then:
document.querySelector('km-editor').plugins = [...defaultPlugins(), myPlugin];Toolbar / menu items are web-components-core action items. A registered command
name is a built-in ('bold', { action: 'insert-link', text: 'Insert link' }) — its
text, icon, tooltip, shortcut and toggled / disabled state come from the command. Custom
items use action: 'custom' + id and onClick(detail); dividers are
{ divider: true } (or createMenuDivider()):
const myPlugin = definePlugin({
name: 'save',
toolbarGroups: [{
id: 'save',
text: 'Save',
items: ['undo', 'redo', { divider: true }, {
action: 'custom', id: 'save', text: 'Save', icon: '💾',
getIsDisabledCallback: ({ state }) => state.doc.textContent.length === 0,
onClick: ({ controller }) => api.save(controller.getMarkdown()),
}],
}],
});
editor.beforeActionCallback = ({ action }) => (action === 'insert-image' ? false : undefined); // false cancelsWriting plugins (schema nodes/marks, commands, keybindings, toolbar/menu items,
the Markdown-serializer contract) and the content-pipeline layer are covered in
docs/ — see the Pipelines guide (with
diagrams) — plus PLAN.md and the PIPELINES.md
design note.
Modern evergreen browsers — anything with native customElements and Shadow DOM
(Chrome/Edge, Firefox, Safari 15.4+). No polyfills are shipped.
npm install
npm run dev # examples hub + pages on http://localhost:12700
npm run build # CEM analyze + library build (dist/)
npm test # unit tests (Vitest)
npm run test:e2e # e2e tests (Playwright)The example site (hub + per-feature pages) runs on
@keenmate/web-components-devkit:
npm run build:examples produces the static dist-examples/ site, and make image-build packages it with nginx. make lists every target.
MIT © Keenmate s.r.o. — see LICENSE.