Skip to content
FrameworkJavaScript

Sanitizer API: how content is cleaned

Clean and sanitize HTML content to prevent XSS attacks. A tool's `static get sanitize()` may also map a data field to the string `'plaintext'` instead of a tag map, which marks that field as literal source text rather than markup.

Edit this page on GitHub

Reaching the editor instance

The methods below run on the editor you created with new Blok(). They are available once editor.isReady resolves.

TypeScript
// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');

Methods

sanitizer.clean(taintString, config)

string

Clean HTML string using the provided sanitizer configuration. `'plaintext'` entries are field-level directives, not tag rules, so `clean()` filters them out of the config before parsing. Allowlisting `href`/`src` allows the attribute, not its scheme — `clean()` additionally drops URL values that can execute (`javascript:`, `data:text/html`, `data:image/svg+xml`), so an allowlisted anchor can never come back as a live script link.

When to use

Strip unwanted HTML against a rule set before inserting external content — your defence for paste and imported strings.

TypeScript
const dirtyHtml = '<script>alert("xss")</script><p>Hello</p>';
const clean = editor.sanitizer.clean(dirtyHtml, {
  p: true,  // Allow <p> tags
  b: true   // Allow <b> tags
});
// Returns: '<p>Hello</p>' (script tag removed)

const link = editor.sanitizer.clean('<a href="javascript:alert(1)">x</a>', { a: { href: true } });
// Returns: '<a>x</a>' (executable scheme dropped, text kept)

Properties

PropertyTypeDescription
plaintext'plaintext'A field-level sanitizer rule a tool declares in `static get sanitize()`, and part of the `SanitizerRule` union exported from the package root. Sanitization is an HTML parse: it entity-encodes bare `<`/`&` and drops text shaped like a stray end tag — irrecoverable corruption for a field holding literal source text, such as a code block's `code`. A field marked `'plaintext'` skips tag sanitization, the URL-scheme pass and the editor-level global sanitizer, and round-trips byte-identical. It is declared as a plain string literal rather than a Symbol, so tool sanitize configs survive JSON and `structuredClone`.
TypeScript
// A tool declares which of its data fields are markup and which are literal text
class CodeTool {
  static get sanitize() {
    return {
      code: 'plaintext',            // literal source — never HTML-parsed
      caption: { b: true, i: true } // markup — sanitized against these tags
    };
  }
}