Vue Sanitize Directive

Common errors

• Failed to resolve directive: sanitize

  cause The `vue-sanitize-directive` plugin has not been correctly installed and registered with your Vue application instance.
  fix Ensure you have called `app.use(VueSanitize)` (for Vue 3) or `Vue.use(VueSanitize)` (for Vue 2) in your application's entry point (e.g., `main.ts` or `main.js`) after importing `VueSanitize`.

• My HTML is not being sanitized as expected; some tags or attributes are still present.

  cause This often occurs after upgrading to `vue-sanitize-directive` v0.2.0+, due to breaking changes in `sanitize-html` v2.x which introduced new, stricter default allowed tags and attributes. Your content might contain tags that are no longer allowed by default.
  fix If specific tags or attributes are needed, provide a custom allowlist array as the first argument to the directive: `<div v-sanitize="[myCustomAllowlist, unsafeHtml]"></div>`. Consult the `sanitize-html` documentation for detailed configuration options.

Warnings

• breaking Version 0.2.0 introduced a breaking change by updating the underlying `sanitize-html` library to 2.7.0. `sanitize-html` version 2.x has significantly different default allowed tags and attributes compared to 1.x.
  Fix: Review the `sanitize-html` changelog for version 2.x to understand new defaults and explicitly configure your allowlist if your application relied on previous `sanitize-html` defaults for specific tags or attributes. You may need to provide an array of `[allowedTags, unsafeHtmlString]` to the directive.
• gotcha Client-side HTML sanitization using `v-sanitize` should not be the sole security measure for user-provided input. Backend validation and sanitization are crucial to prevent XSS and other vulnerabilities, especially before storing data in a database.
  Fix: Always implement robust server-side sanitization and validation for any user-generated content submitted to your application. Use client-side sanitization primarily for display purposes or when backend control is genuinely unavailable.
• gotcha The `.nothing` modifier effectively bypasses all sanitization, making `v-sanitize.nothing` functionally equivalent to `v-html`. Using this modifier with untrusted input can introduce Cross-Site Scripting (XSS) vulnerabilities.
  Fix: Only use `v-sanitize.nothing` when you are absolutely certain the HTML content is safe and fully trusted. For any untrusted or user-generated content, rely on the default `v-sanitize` behavior or specific modifiers like `.strip`, `.basic`, or a custom allowlist.
• gotcha `sanitize-html` (the underlying library) version 2.7.0 and prior had known vulnerabilities, including Regular Expression Denial of Service (ReDoS) and Information Exposure issues. While `vue-sanitize-directive` bundles `sanitize-html`, older bundled versions might be susceptible.
  Fix: Ensure you are using the latest version of `vue-sanitize-directive` (0.2.1 or newer) to benefit from any `sanitize-html` dependency updates that address security vulnerabilities. Periodically check for updates to `vue-sanitize-directive`.

Install

• npm install vue-sanitize-directive npm
• yarn add vue-sanitize-directive yarn
• pnpm add vue-sanitize-directive pnpm

Imports

• VueSanitize
  wrong:

  const VueSanitize = require('vue-sanitize-directive')

  correct:

  import VueSanitize from 'vue-sanitize-directive'

  Used for global plugin registration with `Vue.use()` (Vue 2) or `app.use()` (Vue 3). For ESM-only projects, `require` will cause issues.
• v-sanitize

  <div v-sanitize="unsafeHtml"></div>

  This is a global directive registered via the plugin. It is not imported directly. Apply to HTML elements.
• VueSanitizeDirectiveSSR

  import { VueSanitizeDirectiveSSR } from 'vue-sanitize-directive'

  Only for experimental SSR support in Vue 2.x. Most users will not need to import this directly.

Quickstart

This quickstart demonstrates how to install and globally register `vue-sanitize-directive` for a Vue 3 application. It showcases the default sanitization, `.strip` modifier, applying a custom allowlist, and the `.nothing` modifier, highlighting how the directive cleans potentially unsafe HTML content.

import { createApp } from 'vue';
import VueSanitize from 'vue-sanitize-directive';

const app = createApp({
  data() {
    return {
      unsafeHtml: '<p>Hello <script>alert("XSS")</script> World! <a href="javascript:alert(\'XSS\')">Click me</a> <span style="color: red;">Red Text</span></p>',
      anotherUnsafeHtml: '<div><img src="x" onerror="alert(\'XSS\')"></div>',
      customAllowedTags: ['p', 'span', 'strong']
    };
  },
  template: `
    <div>
      <h1>Vue Sanitize Directive Demo</h1>

      <h2>Default (.basic) Sanitization</h2>
      <p>Original: {{ unsafeHtml }}</p>
      <div v-sanitize="unsafeHtml"></div>
      <hr>

      <h2>.strip Modifier (removes all tags)</h2>
      <p>Original: {{ unsafeHtml }}</p>
      <div v-sanitize.strip="unsafeHtml"></div>
      <hr>

      <h2>Custom Allowlist (only p, span, strong)</h2>
      <p>Original: {{ unsafeHtml }}</p>
      <div v-sanitize="[customAllowedTags, unsafeHtml]"></div>
      <hr>

      <h2>.nothing Modifier (be careful!)</h2>
      <p>Original: {{ anotherUnsafeHtml }}</p>
      <div v-sanitize.nothing="anotherUnsafeHtml"></div>
    </div>
  `
});
app.use(VueSanitize);
app.mount('#app');