JavaScript Document securitypolicyviolation Event

What You’ll Learn

The Document securitypolicyviolation event fires when a Content Security Policy (CSP) is violated. Learn how to listen on document, read SecurityPolicyViolationEvent fields like blockedURI and violatedDirective, and practice with five try-it labs.

Introduction

A Content Security Policy tells the browser which scripts, images, styles, and other resources a page is allowed to load. When something breaks that policy—for example an image from a blocked host—the browser can fire securitypolicyviolation on the Document.

The event object is a SecurityPolicyViolationEvent. It carries details such as which URI was blocked and which CSP directive was violated, so you can log or report the problem without guessing.

Understanding Document securitypolicyviolation

A standard Document event that answers: “Did this page just break its Content Security Policy?”

• Fires when a Content Security Policy is violated (MDN).
• Bubbles to the Window and is composed.
• Listen on document or window (recommended top-level targets).
• Event type — SecurityPolicyViolationEvent (inherits from Event).
• Handler — document.onsecuritypolicyviolation or addEventListener("securitypolicyviolation", ...).
• Status — Baseline Widely available since March 2022 (MDN).

📝 Syntax

Use the event name with addEventListener, or set the handler property:

addEventListener("securitypolicyviolation", (event) => { });

onsecuritypolicyviolation = (event) => { };

Event type

A SecurityPolicyViolationEvent, which inherits from the generic Event type. It bubbles to Window and is composed.

MDN-style handlers

document.onsecuritypolicyviolation = (e) => {
  // Handle SecurityPolicyViolationEvent e here
};

document.addEventListener("securitypolicyviolation", (e) => {
  // Handle SecurityPolicyViolationEvent e here
});

Useful event properties

⚖️ CSP event vs HTTP headers

Examples Gallery

Examples follow MDN Document: securitypolicyviolation event. Try-it labs use a page CSP meta tag that blocks images from other hosts, then load a blocked <img> so you can inspect the event. Some sandboxes may limit CSP—feature-detect and fall back to a synthetic event when needed.

document.addEventListener("securitypolicyviolation", (e) => {
  console.log(e.blockedURI);
  console.log(e.violatedDirective);
  console.log(e.originalPolicy);
});

https://example.com/x.png
img-src
img-src 'none'

const out = document.getElementById("out");

document.onsecuritypolicyviolation = (e) => {
  out.textContent =
    "Blocked: " + e.blockedURI +
    " | directive: " + e.violatedDirective;
};

Blocked: https://example.com/x.png | directive: img-src

const out = document.getElementById("out");

document.addEventListener("securitypolicyviolation", (e) => {
  out.textContent =
    "disposition: " + e.disposition + "\n" +
    "effectiveDirective: " + e.effectiveDirective + "\n" +
    "documentURI: " + e.documentURI + "\n" +
    "blockedURI: " + e.blockedURI;
});

disposition: enforce
effectiveDirective: img-src
documentURI: https://…
blockedURI: https://example.com/x.png

// Page head also needs:
// 

const out = document.getElementById("out");

document.addEventListener("securitypolicyviolation", (e) => {
  out.textContent =
    "CSP violation: " + e.violatedDirective +
    " blocked " + e.blockedURI;
});

const img = document.createElement("img");
img.alt = "blocked demo";
img.src = "https://example.com/csp-demo.png";
document.body.appendChild(img);

CSP violation: img-src blocked https://example.com/csp-demo.png

const out = document.getElementById("out");

document.addEventListener("securitypolicyviolation", (e) => {
  out.textContent =
    "Heard violation: " + e.violatedDirective +
    " → " + e.blockedURI;
});

document.getElementById("btn").addEventListener("click", () => {
  if (typeof SecurityPolicyViolationEvent !== "function") {
    out.textContent = "SecurityPolicyViolationEvent constructor missing";
    return;
  }
  document.dispatchEvent(
    new SecurityPolicyViolationEvent("securitypolicyviolation", {
      blockedURI: "https://cdn.example/demo.js",
      violatedDirective: "script-src",
      effectiveDirective: "script-src",
      originalPolicy: "script-src 'self'",
      disposition: "report",
      documentURI: location.href,
      statusCode: 200
    })
  );
});

Heard violation: script-src → https://cdn.example/demo.js

🚀 Common Use Cases

• Logging CSP failures to your monitoring or analytics pipeline.
• Debugging why a script, image, font, or frame was blocked.
• Showing a gentle “resource blocked by security policy” notice in admin UIs.
• Comparing enforce vs report-only rollouts via disposition.
• Teaching beginners how CSP connects HTTP policy to JavaScript events.

🔧 How It Works

📝 Notes

• Baseline Widely available (since March 2022)—no Deprecated / Experimental / Non-standard banner.
• Bubbles to Window and is composed—still prefer top-level listeners.
• Blocked elements often target document directly (MDN), not the element itself.
• The event observes violations; fixing them means adjusting your CSP policy.
• Related learning: selectionchange, scrollsnapchanging, JavaScript hub.

💡 Best Practices

❓ Frequently Asked Questions