JavaScript Document featurePolicy Property

What You’ll Learn

Document.featurePolicy is a read-only instance property that returns a FeaturePolicy object for inspecting Permissions Policy on the document. Learn feature detection, allowsFeature, allowlists, the Feature Policy → Permissions Policy rename, and five examples with try-it labs.

Introduction

Browsers can restrict powerful features (camera, microphone, geolocation, fullscreen, and more) with Permissions Policy—formerly called Feature Policy. Sites usually set it with the Permissions-Policy HTTP response header and with iframe allow attributes.

MDN: document.featurePolicy returns the FeaturePolicy interface, a simple API for inspecting those policies on a document. It does not replace the HTTP header; it only lets scripts ask what is currently allowed.

Related Document tutorials: embeds, domain, Document constructor.

Understanding Document.featurePolicy

A read-only instance property on Document. Its value is a FeaturePolicy object for the current document (MDN).

• Value — FeaturePolicy (inspect Permissions Policy).
• Read-only — you do not assign a new object to document.featurePolicy.
• Experimental + Non-standard — not for portable production apps (MDN).
• Iframe twin — some engines also expose HTMLIFrameElement.featurePolicy.
• Not user permission — policy allow ≠ user clicked “Allow” in a prompt.

📝 Syntax

document.featurePolicy

Value

A FeaturePolicy object that can be used to inspect the Permissions Policy settings applied to the document (MDN).

Feature detection

if ("featurePolicy" in document) {
  const policy = document.featurePolicy;
  // Safe to call methods on browsers that expose it
} else {
  console.log("document.featurePolicy not available");
}

🔧 FeaturePolicy methods (MDN)

All of these methods are themselves experimental and non-standard on MDN. Unknown feature names may yield empty allowlists or warnings.

⚖️ Policy vs permission vs this API

🛡️ Configuring policy (recommended path)

Production sites usually declare policy in HTTP, not via this JS property. Example shape (simplified):

Permissions-Policy: camera=(), microphone=(), geolocation=(self)

For iframes, combine the parent policy with the frame’s allow attribute. The most restrictive intersection wins.

Examples Gallery

Examples follow MDN Document: featurePolicy and the FeaturePolicy methods. Outputs vary by browser—always feature-detect.

if ("featurePolicy" in document) {
  console.log("FeaturePolicy available");
  console.log(typeof document.featurePolicy);
} else {
  console.log("Not supported in this browser");
}

FeaturePolicy available
object

const featurePolicy = document.featurePolicy;
const allowed = featurePolicy.allowsFeature("camera");

if (allowed) {
  console.log("FP allows camera.");
} else {
  console.log("FP does not allow camera.");
}
// User may still need to grant permission separately

FP allows camera.

const fp = document.featurePolicy;
const supported = fp.features();
const allowed = fp.allowedFeatures();

console.log("supported count:", supported.length);
console.log("allowed count:", allowed.length);
console.log("sample allowed:", allowed.slice(0, 5));

supported count: 40
allowed count: 35
sample allowed: camera, fullscreen, geolocation, ...

const featurePolicy = document.featurePolicy;
const allowlist = featurePolicy.getAllowlistForFeature("camera");

for (const origin of allowlist) {
  console.log(origin);
}
// Often ["*"] or ["https://your-site.example"] depending on headers

*

function policyAllowsCamera() {
  if (!("featurePolicy" in document)) {
    // Unknown — do not hard-block; fall back to trying the API
    return null;
  }
  return document.featurePolicy.allowsFeature("camera");
}

const result = policyAllowsCamera();
if (result === false) {
  console.log("Hide camera UI — blocked by Permissions Policy");
} else if (result === true) {
  console.log("Policy OK — still need user permission for getUserMedia");
} else {
  console.log("Inspector missing — feature-detect getUserMedia instead");
}

Policy OK — still need user permission for getUserMedia

🚀 Common Use Cases

• Diagnostics — debug why camera/mic APIs fail in an embed.
• Teaching Permissions Policy — show allowlists live in supporting browsers.
• Optional UI hints — hide controls when policy clearly blocks a feature.
• Iframe audits — compare document vs iframe policy where both exist.
• Not primary config — still set policy with HTTP headers / allow.
• Legacy Feature Policy docs — map old name to today’s Permissions Policy.

📝 Notes

• MDN: Experimental and Non-standard — both banners shown above; not Deprecated.
• MDN: does not appear to be defined in any specification.
• Feature Policy was renamed to Permissions Policy; the JS property name lagged behind.
• Always feature-detect before calling methods.
• Related: embeds, domain, Document constructor.

💡 Best Practices