Revision 1046694 of mask-size

<div>{{CSSRef}}{{SeeCompatTable}}</div>

<h2 id="Summary">Summary</h2>

<p>The <strong><code>mask-size</code></strong> <a href="/en-US/docs/Web/CSS">CSS</a> property specifies the sizes of the mask images. The size of the image can be fully or partially constrained&nbsp;in order to preserve its intrinsic ratio.</p>

<div class="note"><strong>Note:</strong> If the value of this property is not set in a {{cssxref("mask")}} shorthand property that is applied to the element after the <code>mask-size</code> CSS property, the value of this property is then reset to its initial value by the shorthand property.</div>

<p>{{cssinfo}}</p>

<h2 id="Syntax">Syntax</h2>

<pre class="brush: css">
/* Keywords syntax */
mask-size: cover;
mask-size: contain;

/* One-value syntax */
/* the width of the image (height set to 'auto') */
mask-size: 50%;
mask-size: 3em;
mask-size: 12px;
mask-size: auto;

/* Two-value syntax */
/* first value: width of the image, second value: height */
mask-size: 50% auto;
mask-size: 3em 25%;
mask-size: auto 6px;
mask-size: auto auto;

/* Multiple values */
/* Do not confuse this with mask-size: auto auto */
mask-size: auto, auto;
mask-size: 50%, 25%, 25%;
mask-size: 6px, auto, contain;

/* Global values */
mask-size: inherit;
mask-size: initial;
mask-size: unset;
</pre>

<h3 id="Values">Values</h3>

<dl>
 <dt><code>&lt;length&gt;</code></dt>
 <dd>A <code>{{cssxref("")}}</code> value&nbsp;scales the mask image to the specified length in the corresponding dimension. Negative lengths are not allowed.</dd>
 <dt><code>&lt;percentage&gt;</code></dt>
 <dd>A {{cssxref("&lt;percentage&gt;")}} value scales the mask image in the corresponding dimension to the specified percentage of the mask positioning area, which is determined by the value of {{cssxref("mask-origin")}}. The mask positioning area is, by default, the area containing the content of the box and its padding; the area may also be changed to just the content or to the area containing borders, padding&nbsp;and content. Negative percentages are not allowed.</dd>
 <dt><code>auto</code></dt>
 <dd>A keyword that scales the mask image in the corresponding directions in order to maintain&nbsp;its intrinsic proportion.</dd>
 <dt><code>contain</code></dt>
 <dd>A keyword that scales the image as large as possible and maintains image aspect ratio (image doesn't get squished). The image is <strong>letterboxed</strong> within the container. The image is automatically centered unless over-ridden by another property such as {{cssxref("mask-position")}}.</dd>
 <dt><code>cover</code></dt>
 <dd>A keyword that is the inverse of <code>contain</code>. Scales the image as large as possible and maintains image aspect ratio (image doesn't get squished). The image "covers" the entire width or height of the container. When the image and container have different dimensions, <em>the image is clipped</em> either on left/right or &nbsp;at&nbsp;top/bottom.</dd>
</dl>

<p>The interpretation of possible values depends on the image's intrinsic dimensions (width and height) and intrinsic proportion (ratio of width and height). A bitmap image always has intrinsic dimensions and an intrinsic proportion. A vector image may have both intrisic dimensions&nbsp;and thus it has&nbsp;an intrinsic proportion too. It also may have one or no intrinsic dimensions&nbsp;and in either case it might or might not have an intrinsic proportion. Gradients are treated as images with no intrinsic dimensions or intrinsic proportion.</p>

<p>The rendered size of the mask image is then computed as follows:</p>

<dl>
 <dt>If both components of <code>mask-size</code> are specified and are not <code>auto</code>:</dt>
 <dd>The mask image renders at the specified size.</dd>
 <dt>If the <code>mask-size</code> is <code>contain</code> or <code>cover</code>:</dt>
 <dd>The image is rendered by&nbsp;preserving its intrinsic proportion&nbsp;at the largest size contained within&nbsp;or covering&nbsp;the mask positioning area. If the image has no intrinsic proportion, then it is rendered at the size of the mask positioning area.</dd>
 <dt>If the <code>mask-size</code> is <code>auto</code> or <code>auto auto</code>:</dt>
 <dd>If the image has both intrinsic dimensions, it is rendered at that size. If it has no intrinsic dimensions and no intrinsic proportion, it is rendered at the size of the mask positioning area. If it has no dimensions but has a proportion, it's rendered as if <code>contain</code> had been specified instead. If the image has one intrinsic dimension and a proportion, it's rendered at the size determined by that one dimension and the proportion. If the image has one intrinsic dimension but no proportion, it's rendered using the intrinsic dimension and the corresponding dimension of the mask positioning area.</dd>
 <dt>If <code>mask-size</code> has one <code>auto</code> component and one non-<code>auto</code> component:</dt>
 <dd>If the image has an intrinsic proportion, then render it using the specified dimension&nbsp;and compute the other dimension from the specified dimension and the intrinsic proportion. If the image has no intrinsic proportion, use the specified dimension for that dimension. For the other dimension, use the image's corresponding intrinsic dimension if there is one.&nbsp; If there is no such intrinsic dimension, use the corresponding dimension of the mask positioning area.</dd>
</dl>

<h3 id="Formal_syntax">Formal syntax</h3>

<pre class="syntaxbox">
{{csssyntax}}</pre>

<h2 id="Example">Example</h2>

<p>{{TODO}}</p>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName("CSS Masks", "#the-mask-size", "mask-size")}}</td>
   <td>{{Spec2("CSS Masks")}}</td>
   <td>Initial definition</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}<sup>[1]</sup></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE&nbsp;Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}<sup>[1]</sup></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Gecko currently doesn't implement this feature. See {{bug("1251161")}}.</p>