Vue Safe HTML Directive

Common errors

• My HTML attributes (like `href`, `class`, `style`) are disappearing after `v-safe-html` is applied!

  cause Since version 2.2.0, `vue-safe-html` strips all HTML attributes by default for enhanced security. Only explicitly allowed attributes will be preserved.
  fix When installing the plugin, configure `allowedAttributes` with an array of attribute names you wish to retain: `Vue.use(VueSafeHTML, { allowedAttributes: ['href', 'class', 'title'] })`.

• I'm using `vue-safe-html` but still seeing XSS vulnerabilities in my application.

  cause The library is a basic HTML tag-stripper and is explicitly stated as 'not XSS-safe'. It primarily focuses on whitelisting tags, not comprehensive XSS protection.
  fix Do not rely on `vue-safe-html` alone for XSS protection. Implement server-side sanitization, or use a dedicated, robust client-side XSS sanitization library (e.g., DOMPurify) as an additional layer of defense for untrusted HTML content.

• Certain HTML tags (e.g., `<img>`, `<span>`) are stripped even though I want them to render.

  cause `vue-safe-html` operates on an `allowedTags` whitelist. By default, only a very limited set of common text formatting tags are allowed.
  fix Extend the default `allowedTags` array when installing the plugin: `import VueSafeHTML, { allowedTags } from 'vue-safe-html'; Vue.use(VueSafeHTML, { allowedTags: [...allowedTags, 'img', 'span'] })`. Alternatively, use directive modifiers for local overrides: `<div v-safe-html.img.span="myHtml"></div>`.

Warnings

• gotcha This library is explicitly NOT XSS-safe. It only strips tags programmatically based on a whitelist and does not provide comprehensive protection against all forms of Cross-Site Scripting attacks. Do not rely on it as a sole security measure for untrusted HTML.
  Fix: For full XSS protection, use a dedicated, robust sanitization library that handles attributes, CSS, URLs, and other vectors, or sanitize content on the server-side before rendering. Consider libraries like `dompurify` in conjunction or as an alternative.
• breaking Starting from version 2.2.0, HTML attributes are *completely removed* by default. If you were relying on attributes like `href`, `class`, or `src` to be preserved, they will now be stripped unless explicitly allowed.
  Fix: Explicitly define `allowedAttributes` when installing the plugin via `Vue.use(VueSafeHTML, { allowedAttributes: ['href', 'title', 'target'] })` to allow specific attributes to be rendered on their respective allowed tags.
• breaking The regex for sanitizing HTML tags was rewritten in v2.2.0, addressing several issues where input tags or tags starting with certain characters were not stripped correctly. While this improves security, it might alter behavior for previously malformed or unexpectedly allowed tags.
  Fix: Review any edge cases involving unusual or malformed HTML that previously passed through the sanitizer to ensure desired behavior is maintained. Ensure your `allowedTags` configuration is precise.
• gotcha If you provide an empty array to the `allowedTags` option (e.g., `Vue.use(VueSafeHTML, { allowedTags: [] })`), all HTML tags will be stripped from the content, leaving only plain text.
  Fix: Only set `allowedTags: []` if you explicitly intend to remove all HTML formatting. To allow specific tags, provide a non-empty array of tag names (e.g., `['p', 'strong']`).

Install

• npm install vue-safe-html npm
• yarn add vue-safe-html yarn
• pnpm add vue-safe-html pnpm

Imports

• VueSafeHTML
  wrong:

  const VueSafeHTML = require('vue-safe-html');

  correct:

  import VueSafeHTML from 'vue-safe-html';

  Primary import for registering the plugin with Vue. For modern Vue CLI/Vite projects, ESM import is standard. CommonJS `require` can be used in older Node/Webpack setups, though not explicitly recommended in v3 documentation examples.
• allowedTags

  import VueSafeHTML, { allowedTags } from 'vue-safe-html';

  Import `allowedTags` named export to extend the default list of allowed tags when configuring the plugin, rather than overwriting it entirely.
• v-safe-html

  <div v-safe-html="myHtmlContent"></div>

  The directive itself is used directly in the template without explicit JavaScript import, but relies on the plugin being installed via `Vue.use(VueSafeHTML)`.

Quickstart

Demonstrates installation of the `vue-safe-html` plugin globally, passing custom `allowedTags` and `allowedAttributes`, and then using the `v-safe-html` directive in a Vue component to render sanitized HTML, including a local override.

import Vue from 'vue';
import VueSafeHTML from 'vue-safe-html';

// Optionally configure global allowed tags or attributes
Vue.use(VueSafeHTML, {
  allowedTags: ['p', 'strong', 'em', 'a'],
  allowedAttributes: ['href', 'title']
});

new Vue({
  el: '#app',
  data: {
    unsafeHtml: '<script>alert("XSS attempt!")</script><b>Hello</b> <a href="malicious.com" onclick="doEvil()">World</a> <p>This is safe.</p>'
  },
  template: `
    <div id="app">
      <h3>Content with default sanitization:</h3>
      <div v-safe-html="unsafeHtml"></div>
      <h3>Content with local override (only allowing 'p'):</h3>
      <div v-safe-html.p="unsafeHtml"></div>
    </div>
  `
});