Skip to content

Latest commit

 

History

History
146 lines (108 loc) · 6.25 KB

unsized-media.md

File metadata and controls

146 lines (108 loc) · 6.25 KB
Raw

Unsized Media Policy Explainer

loonybear@, last updated: 11/05/2018

Status: available in Chrome behind a flag

Goal

Layout instability is one of the existing problems that are aggravating web experiences. For example, when the size of an <img> element is unspecified, it will cause the content around the <img> element to jump around. This is because the renderer does not know how much space to reserve for an image until the image is loaded, and once the image size is known the renderer will have to re-layout everything, causing the content to shift on the web page.

Unsized media policy is aiming to fix the problem by requiring all media elements to provide a size; if they don't, a default will be chosen, so that the image doesn't change size after loading.

Background: "intrinsicSize"

unsized-media policy is defined to set default value of the intrinsicSize attribute if not otherwise specified.

intrinsicSize attribute tells the browser to ignore the actual intrinsic size of the image and pretend it’s the size specified in the attribute. Please read the explainer for "intrinsicSize" attribute for more details.

What is "unsized-media"?

unsized-media is a policy-controlled feature. It restricts images to have specified sizes. When a document is disallowed to use unsized-media, the intrinsic size (defined by the 'intrinsicSize' attribute) of <img>, <video>, and <svg:image> elements will be set to default ("300 x 150") unless otherwise specified. So, for exmaple:

  • If no width/height are specified, and no intrinsicSize value is set, then the image's intrinsic size is set to default (300px by 150px) and the image is rendered by the default dimension (300px by 150px)
  • If the width (or height) is set, but intrinsicSize value is not specified, then the image's intrinsic size is set to default (300px by 150px) and the image's height (or widht) is set to maintain the default intrinsic aspect ratio (300 / 150)
  • If the width and height are set on the image, but intrinsicSize value is not specified, then the image's intrinsic size is set to default (300px by 150px) but the image is rendered by the width and height specified.

Note: When 'intrinsic size' is set to default, a image's naturalWidth/naturalHeight will return the default value (300/150).

  • If no width/height are specified, but intrinsicSize value is set, then the image is rendered by the dimension specified by the intrinsicSize attribute
  • If the width (or height) is set, and intrinsicSize value is set, then the image's height (or width) is set to maintain the aspect ratio specified by the intrinsicSize attribute
  • If the width and height are set on the image, and intrinsicSize value is specified, then the image is rendered by the width and height specified and the image's intrinsic size is overridden by 'intrinsicSize'

Specification

  • The default allowlist for unsized-media is *. In other words, unsized-media is enabled for all origins by default.

  • An unsized-media policy can be specified via:

    1. HTTP "Feature-Policy" response header

    Feature-Policy: unsized-media 'none';

    In this example, unsized-media is disabled for all frames including the main frame. All "media" elements will be using the default intrinsicSize ("300 X 150") unless otherwise specified.

    2. "allow" attribute in <iframe>

    <iframe src="https://example.com" allow="unsized-media 'self' https://foo.com;">

    In this example, unsized-media is disabled everywhere except on the origin of the main document and on https://foo.com.

Examples

Feature-Policy: unsized-media 'none'; Feature-Policy: unsized-media *; 
"example0.com"
<img width="300" height="200" src="cat.jpg">
<img width="300" height="200" intrinsicSize="450x300" src="cat.jpg">
<img style="width:300px; height:200px" src="cat.jpg">
<img style="width:300px; height:200px" intrinsicSize="450x300" src="cat.jpg">

For any <img>, <video>, or <svg:image> element, if its width and height are specified, then the element will be rendered using its specified size, regardless of the state of the policy.

Feature-Policy: unsized-media 'none'; Feature-Policy: unsized-media *; 
"example1.com"
<img width="300" src="cat.jpg">
<img width="300" intrinsicSize="450x300" src="cat.jpg">
<img style="height:300px;" src="cat.jpg">
<img style="height:300px;" intrinsicSize="450x300" src="cat.jpg">

For an <img>, <video>, or <svg:image> element, if one dimension is specified, the other dimension will be determined by the intrinsic aspect ratio (if not specified by the intrinsicSize attribute, use "300 x 150" as default), when unsized-media is disallowed.

Feature-Policy: unsized-media 'none'; Feature-Policy: unsized-media *; 
"example2.com"
<img src="cat.jpg">
<img src="cat.jpg" intrinsicSize="450x300">

For an <img>, <video>, or <svg:image> element, if both dimensions are unspecified, use intrinsic dimensions (if unspecified by the intrinsicSize attribute, use "300 x 150" as default), when unsized-media is disallowed.