rehype-sanitize

rehype-sanitize is a rehype (unified) plugin that makes HTML safe by cleaning a hast syntax tree against a configurable schema, dropping any element or attribute that is not explicitly allowed. It defaults to GitHub’s sanitation rules, so untrusted markup, inline event handlers, dangerous URLs, and injected scripts are stripped out before rendering.

Built on hast-util-sanitize, it slots into any unified/rehype pipeline between parsing and stringifying. It is the standard way to defend against cross-site scripting when rendering user-authored or plugin-generated HTML, and its schema can be extended to safely permit math, syntax highlighting, or other trusted markup.

What You Get

• A drop-in rehype plugin that sanitizes a hast tree against a configurable allowlist schema.
• A secure default schema (defaultSchema) modeled on GitHub’s sanitation rules, requiring no configuration to be safe.
• Protection against XSS, DOM clobbering (via user-content- id/name prefixing), dangerous URLs, and inline event handlers.
• Full TypeScript types (via JSDoc) and ESM-only distribution with 100% type and test coverage.
• Extensible schemas so you can safely opt in to math, syntax highlighting, or other trusted markup.

Common Use Cases

• Sanitizing user-authored HTML or Markdown-derived HTML before rendering it on a page.
• Hardening a rehype/remark content pipeline against XSS from untrusted authors or third-party plugins.
• Allowing specific trusted classes so plugins like rehype-katex or rehype-highlight can run safely.
• Preventing DOM clobbering when generating heading IDs from user content.

Under The Hood

Architecture

The package is intentionally tiny. index.js re-exports defaultSchema from hast-util-sanitize and the default plugin from lib/index.js. lib/index.js defines rehypeSanitize(options), which returns a unified transformer that calls sanitize(tree, options) on the incoming hast Root and returns the cleaned tree. All actual sanitation logic lives in the underlying hast-util-sanitize utility; this plugin is the thin unified-integration layer that lets you drop sanitation into a .use() chain between parse and stringify.

Tech Stack

Written in modern ESM JavaScript (Node 16+), typed entirely through JSDoc with TypeScript checking (tsconfig.json, type-coverage at 100%). Runtime dependencies are just hast-util-sanitize (the sanitizer) and @types/hast (types). Tooling includes xo and prettier for linting/formatting, c8 for coverage, and the built-in node:test runner. The build compiles type declarations with tsc.

Code Quality

Quality is high and rigorously enforced: test.js uses node:test to verify the public API surface, default sanitation of an onmouseover attribute, and schema-merged options, with c8 enforcing 100% line coverage and type-coverage enforcing 100% typed coverage in strict mode. The code is small, documented with JSDoc, and follows consistent unified-ecosystem conventions.

API Design

The public API is minimal and ergonomic: a default export used as .use(rehypeSanitize[, schema]) plus a named defaultSchema export for extension. Being safe by default with zero configuration is the key DX win, and the extensive README documents real-world schema-extension recipes (math, highlighting, DOM-clobbering mitigation). Familiarity with hast/unified is needed only for advanced schema customization.