Document-Policy

The HTTP Document-Policy response header configures document-level policies controlling how the browser handles rendering behavior, resource constraints, and performance characteristics within the page.

Table of Contents

Usage

The Document-Policy header gives servers control over specific document behaviors at the browser level. While Permissions-Policy governs access to browser APIs using a boolean allow/deny model, Document-Policy targets rendering and resource behavior inside the document with configurable parameters. A permissions policy toggles whether a feature is available. A document policy configures how a feature behaves, accepting threshold values and enumerated states.

Policies are declared as a Structured Header dictionary. Each directive names a behavior and optionally sets a parameter value. Boolean directives use Structured Header boolean syntax. Threshold directives accept decimal or integer values. An optional report-to parameter on each directive names a Reporting API endpoint for violation reports.

Document-Policy: oversized-images=2.0;report-to=img, unsized-media=?0

The Document-Policy-Report-Only response header applies the same syntax but reports violations without enforcing them. This allows production monitoring before committing to enforcement.

Document-Policy-Report-Only: oversized-images=2.0;report-to=img

For embedded content, the Require-Document-Policy response header sets the minimum policy for all nested iframes. The browser sends a Sec-Required-Document-Policy request header on subframe requests, communicating the required policy to the embedded server. If the embedded document does not return a compatible Document-Policy, the browser blocks the content. Individual iframes accept a policy attribute for per-frame constraints.

<iframe src="https://img.example.re/"
  policy="oversized-images=2.0"></iframe>

Note

Document-Policy is partially supported in Chromium-based browsers. The js-profiling directive is enabled by default in Chromium without requiring a flag. Most other directives remain behind the "Experimental Web Platform features" flag (chrome://flags/#enable-experimental-web-platform-features) and are not yet shipped for general use.

Directives

force-load-at-top

The force-load-at-top directive instructs the browser to load the document scrolled to the top, preventing scroll position restoration or fragment navigation from placing the viewport elsewhere on initial load. Boolean.

js-profiling

The js-profiling directive enables the JavaScript Self-Profiling API for the document. When active, the Profiler constructor becomes available, allowing in-page performance sampling of JavaScript execution. Boolean. Enabled by default in Chromium.

document-write

The document-write directive controls whether document.write() and related APIs are allowed. Disabling this call prevents parser-blocking script injection, a common source of rendering delays. Set to ?0 to block.

sync-script

The sync-script directive controls whether synchronous script loading is permitted. When set to ?0, inline scripts and external scripts without async or defer attributes trigger a policy violation.

sync-xhr

The sync-xhr directive controls whether synchronous XMLHttpRequest calls are allowed. Blocking synchronous XHR prevents main-thread stalls caused by synchronous network requests. Set to ?0 to block.

unsized-media

The unsized-media directive controls whether media elements (images, videos) are required to specify explicit dimensions. When set to ?0, media elements without width and height attributes trigger a policy violation, preventing unexpected layout shifts.

oversized-images

The oversized-images directive sets a maximum ratio between an image's intrinsic dimensions and its display size. Images significantly larger than their rendered area trigger a policy violation. The value is a decimal representing the allowed ratio (e.g., 2.0 allows images up to twice the display size).

lossless-images-max-bpp

The lossless-images-max-bpp directive sets a maximum bits-per-pixel threshold for lossless images. The formula is (image size - 10KB) / image resolution. Images exceeding the threshold trigger a policy violation. The value is a decimal number.

lossy-images-max-bpp

The lossy-images-max-bpp directive sets a maximum bits-per-pixel threshold for lossy-compressed images. The formula is (image size - 1KB) / image resolution. The value is a decimal number.

font-display-late-swap

The font-display-late-swap directive overrides all font-display values to optional, preventing late font swaps from causing layout shifts. Boolean. Set to ?0 to enforce.

layout-animations

The layout-animations directive restricts CSS animations to compositor-friendly properties: opacity, transform, and filter. Animations targeting properties causing layout recalculation (like width or top) trigger a policy violation. Boolean. Set to ?0 to enforce.

include-js-call-stacks-in-crash-reports

The include-js-call-stacks-in-crash-reports directive opts the document into including JavaScript call stacks in crash reports sent to the browser's crash reporting infrastructure. Boolean.

Example

A document policy enforcing image best practices. The oversized-images directive limits images to twice their display dimensions. The unsized-media directive requires explicit sizing on all media elements. Violations are reported to the perf endpoint.

Document-Policy: oversized-images=2.0;report-to=perf, unsized-media=?0;report-to=perf

A site enabling the JavaScript Self-Profiling API. The js-profiling directive makes the Profiler constructor available to scripts on the page.

Document-Policy: js-profiling

A report-only deployment monitoring synchronous API usage before enforcement. Violations generate reports without blocking the behavior.

Document-Policy-Report-Only: sync-xhr=?0;report-to=perf, document-write=?0;report-to=perf

An iframe requiring embedded content to comply with image policies. The browser sends Sec-Required-Document-Policy on the subframe request. If the embedded server does not return a compatible policy, the browser blocks the content.

Require-Document-Policy: oversized-images=2.0

Multiple directives combining performance enforcement. Synchronous scripts, synchronous XHR, and document.write() are all blocked, while crash report call stacks are enabled.

Document-Policy: sync-script=?0, sync-xhr=?0, document-write=?0, include-js-call-stacks-in-crash-reports

Takeaway

The Document-Policy header configures browser- enforced policies over document rendering behavior, resource constraints, and performance characteristics. The header complements Permissions-Policy by offering parametric configuration rather than binary feature toggling, with report-only monitoring through Document-Policy-Report-Only.

See also

Last updated: March 6, 2026