CSS Image Values and Replaced Content Module Level 3

4.1. Image References and Image Slices: the ‘url()’ notation

The simplest way to indicate an image is to reference an image file by URI. This is done with the ‘url()’ notation, defined in [CSS21].

background-image: url(wavy.png);

A portion of an image may be referenced (clipped out and used as a standalone image) by use of fragment identifiers. Need a spec to reference here. Expecting to get one from Media Fragments WG.

background-image: url('logos.png#xywh=10,30,60,20')

4.2. Image Fallbacks: the ‘image()’ notation

The ‘image()’ notation allows an author to specify multiple images, each one a fallback for the previous. The UA must use only the first image that it can load and display. The syntax for ‘image()’ is defined as

<image-list> = image( [ <image-decl> , ]* [ <image-decl> | <color> | <gradient> | <element-reference> ] )

where <image-decl> is given by

<image-decl> = [ <string> | <url-token> ] [ snap? && <resolution> ]?

<url-token> is given as [!#$%&*-~]|{nonascii}|{escape} (i.e. the contents of ‘url()’) using the productions in the CSS2.1 tokenization. The <url-token> must not contain unescaped brackets, commas, white space characters, single quotes (') or double quotes ("); if it does the ‘image()’ containing it is invalid.

Each string or url-token represents the URI of an image. If a resolution is given, then the image must be rendered at the specified resolution. If the ‘snap’ keyword is also specified, and the image is a raster image, then the image must be rendered at the resolution closest to the specified resolution that would result in no pixel rounding. I don't think "no pixel rounding" is the right terminology here... basically we want to avoid blurry images.

The optional color at the end of the list is the fallback color. It is used if, and only if, none of the images can be loaded and displayed (e.g. because they are in unsupported formats, or cannot be found, or are corrupted in some way, or because image loading is disabled in the UA). It is treated as a single-color image with no intrinsic dimensions.

background-image: image(wavy.svg, 'wavy.png' 150dpi, "wavy.gif", blue);

If the URL for the image ends in a file extension (a period followed by letters) of four ascii letters ([a-zA-Z]) or less, then the UA may skip trying to load images whose file extension matches an image format it knows it does not support. For example, a UA that knows it supports JPEG and GIF, but expects to encounter many PNG and SVG images may choose to skip over images with filenames ending in ‘.png’ or ‘.svg’ without loading them to check their MIME type. However it must not skip over images with filenames ending in extensions it doesn't recognize.

4.3. Using Elements as Images: The ‘element()’ notation

The ‘element()’ function allows an author to reference an element in the document that should be used as an image. As the referenced element changes, for example, by the user typing into a <textarea> element or a script drawing into a <canvas> element in HTML, the image produced by the ‘element()’ function stays in sync, allowing dynamic effects such as script-animated background images or previews of the next slide in a slideshow. The syntax for ‘element()’ is defined as:

<element-reference> = element( [<id-selector> | <identifier> ] )

where <id-selector> is an ID selector [SELECT], and <identifier> is an identifer [CSS3VAL].

If the argument to the ‘element()’ function is an ID selector, the function references the element matched by the selector. If it's an identifier, the function references the element who's CSS element reference identifier is the identifier. (CSS does not define how an element acquires a ‘CSS element reference identifier’; that is determined by the host language.) If no element in the document matches the selector, or no element has the identifier as its ‘CSS element reference identifier’, the function represents a fully transparent image with no intrinsic dimensions, equivalent to image(transparent). Otherwise, the function represents an image with width and height equal to the width and height of the referenced element, with an appearance exactly equivalent to that of the referenced element. Whether or not the referenced element is currently being rendered on-screen, for media types where this is relevant, must not affect the appearance of the image represented by the function; the image must always be equivalent to how the element would appear when rendered on-screen. If the document changes so that which element is matched, or whether an element is matched at all, changes, the image represented by the function must change accordingly.

If the argument passed to ‘element()’ isn't an ID selector or an ident, it is a syntax error.

5. Gradients

A gradient is an image that smoothly fades from one color to another. These are commonly used for subtle shading in background images, buttons, and many other things. The two functions described in this section allow an author to specify such an image in a terse syntax, so that the UA can generate the image automatically when rendering the page. Gradients are a type of image, and can be used anywhere an image can, such as in the background-image or list-style-image properties. For official purposes, the syntax of a <gradient> is:

<gradient> = [ <linear-gradient> | <radial-gradient> ]

where <linear-gradient> and <radial-gradient> are defined in their applicable sections below.

In many places this section references a box, such as "the box's top-left corner" or "the box's right side". In all of these circumstances, the "box" refers to the ‘CSS View Box’ (see the "Sizing Images and Objects in CSS" section of this spec for clarification). A gradient has no intrinsic dimensions. This means that, for example, if you use a gradient in a background-image, the "box" will simply be the size of the background area. If you use a gradient in a list-style-image, the "box" will be a 1em square.

5.1. Linear Gradients

A linear gradient is created by specifying a gradient-line and then several colors placed along that line. The image is constructed by creating an infinite canvas and painting it with lines perdendicular to the gradient-line, with the color of the painted line being the color of the gradient-line where the two intersect. This produces a smooth fade from each color to the next, progressing in the specified direction.

5.1.1. linear-gradient() syntax

<linear-gradient> = linear-gradient(
	[ 
		[ [top | bottom] || [left | right] ] 
		|| 
		<angle>
	,]? 
	<color-stop>[, <color-stop>]+
);

The first argument to the function specifies the gradient-line, which gives the gradient a direction and determines how color-stops are positioned. It may be omitted; if so, it defaults to "top".

The gradient-line may be specified in two different ways. The first is by specifying the angle the gradient-line should assume; this uses the standard algebraic notation for angles where 0deg points to the right, 90deg points up, and positive angles go counterclockwise. The starting-point and ending-point of the gradient-line are determined by extending a line in both direction from the center of the box at the angle specified. In the direction of the angle, the ending-point is the point on the gradient-line line where a line drawn perpendicular to the gradient-line would intersect the corner of the box in that direction. The starting-point is determined identically, except in the opposite direction of the angle.

The second way is to simply provide a side or corner of the box that the gradient should start at; the gradient will then automatically angle itself to extend from the specified side or corner to the opposite side or corner in a straight line. To be precise, the gradient is converted to the angle form described in the previous paragraph at used-value time. If a left, bottom, right, or top is given, the used value of the gradient is 0deg, 90deg, 180deg, or 270 deg, respectively. If a corner is given, the used value of the gradient is the angle necessary to place the starting-point of the gradient in that corner of the box.

This example illustrates visually how to calculate the gradient-line from the rules above. This shows the starting and ending-point of the gradient-line, along with the actual gradient, produced by an element with ‘background: linear-gradient(45deg, white, black);’.

Notice how, though the starting-point and ending-point are outside of the box, they're positioned precisely right so that the gradient is pure white exactly at the corner, and pure black exactly at the opposite corner. That's intentional, and will always be true for linear gradients.

The gradient's color stops are typically placed between the starting-point and ending-point on the gradient-line, but this isn't required - the gradient-line extends infinitely in both directions. The starting-point and ending-point are merely arbitrary distance markers - the starting-point defines where 0%, 0px, etc are located when specifying color-stops, and the ending-point defines where 100% is located. Color stops are allowed to have positions before 0% or after 100%.

5.1.2. Linear Gradient Examples

All of the following linear-gradient() examples are presumed to be backgrounds applied to a box that is 200px wide and 100px tall.

Below are various ways of specifying a basic vertical gradient:

linear-gradient(yellow, blue);
linear-gradient(top, yellow, blue);
linear-gradient(bottom, blue, yellow);
linear-gradient(-90deg, yellow, blue);
linear-gradient(270deg, yellow, blue);
linear-gradient(top, yellow 0%, blue 100%);

This gradient goes from the upper-left to the lower-right corner.

linear-gradient(top left, yellow, blue);

This demonstrates the use of an angle in the gradient. Compare this image with the previous example. In both gradients, the top-left of the box is pure yellow, and the bottom-right of the box is pure blue. The difference is in the angle that the gradient follows.

linear-gradient(-45deg, yellow, blue);
linear-gradient(315deg, yellow, blue);

This demonstrates a 3-color gradient, and how to specify the location of a stop explicitly:

linear-gradient(yellow, blue 20%, #0f0);

<radial-gradient> = radial-gradient(
	[<bg-position>,]? 
	[
		[<shape> || <size>]
		|
		[<length> | <percentage>]{2}
	,]? 
	<color-stop>[, <color-stop>]+
)

radial-gradient(yellow, green);
radial-gradient(center, ellipse cover, yellow 0%, green 100%);
radial-gradient(50% 50%, farthest-corner, yellow, green);

radial-gradient(circle, yellow, green);

radial-gradient(red, yellow, green);

radial-gradient(bottom left, farthest-side, red, yellow 50px, green);

radial-gradient(20px 30px, contain, red, yellow, green);
radial-gradient(20px 30px, 20px 30px, red, yellow, green);

radial-gradient(20px 30px, circle contain, red, yellow, green);
radial-gradient(20px 30px, 20px 20px, red, yellow, green);

<color-stop> = <color> [ <percentage> | <length> ]?

6. Sizing Images and Objects in CSS

Images used in CSS may come from a number of sources, from defined image formats (such as gif, jpeg, etc), dedicated markup formats (such as SVG), and CSS-specific formats (such as the linear-gradient() value type defined in this specification). As well, a document may contain many other types of objects, such as video, plugins, or nested documents. These images and objects (just "objects" hereafter) may offer many types of sizing information to CSS, or none at all. This section defines generically the size negotiation model between the image or replaced content object and the CSS layout algorithms.

In order to define this handling, we must define a few terms, to make it easier to refer to various concepts:

intrinsic dimensions

The intrinsic dimensions are defined are the object's preferred, natural size or aspect ratio, if any. There can be an intrinsic height and intrinsic width, defining a definite rectangle. (Most bitmap images fall into this category.) There can be an intrinsic aspect ratio defining the relation of the width to the height, but no definite size. (SVG images designed to scale may fall into this category.) There can be just an intrinsic height or width. Or there can be no intrinsic dimensions at all, implying that the object has no preferred size or aspect ratio. (Embedded documents are often assumed to have no intrinsic size, as are CSS gradients, defined in this specification.)

If an object (such as an icon) has multiple sizes, then the largest size is used. If it has multiple aspect ratios of that size (or of no size), then the aspect ratio closest to the aspect ratio of the default image sizing area is use This is pretty arbitrary.

specified size

The specified size of an object is given by CSS, such as through the `object-fit` or `background-size` properties. The specified size can be a definite width and height, a set of constraints, or a combination thereof.

CSS View Box

The CSS View Box is the result of transforming the intrinsic dimensions into a concrete size, based on the specified size and the default image sizing area. A CSS View Box always has a definite height and width.

default image sizing area

The default image sizing area is a rectangle with a definite height and width used to determine the size of the CSS View Box when both the intrinsic dimensions and specified size are missing dimensions. It varies based on the property that the image is being used as a value in. For background-image, the default image sizing area is the size of the background positioning area of the element. For list-style-image, the default image sizing area is a 1em square. For list-style-image, the default image sizing area is the size of the border box of the element. In any other context, the default image sizing area is a rectangle 300px wide and 150px tall.

Images and objects in CSS are sized as follows:

1. When an image or object is specified in a document, such as through url() value in a background-image property or a @src attribute on an <img> element, CSS queries the object for its intrinsic size.
2. Using the intrinsic dimensions and the specified size, CSS then computes a CSS View Box that defines the size of the region the object will render in, as follows:
   1. If the specified size is just a definite width and height, the CSS View Box must be that width and height.
   2. If the specified size is just a definite width or just a definite height, then the CSS View Box must have the same width or height, as appropriate. The other dimension is calculated as follows:
      1. If the object has an intrinsic aspect ratio, the CSS View Box must have the same aspect ratio..
      2. Otherwise, if the object has an an intrinsic height or intrinsic width (whichever is missing from the specified size), then the CSS View Box must have that height or width.
      3. Otherwise, the CSS View Box must have the same width or height (whichever is missing from the specified size) as the default image sizing area.
   3. If the specified size is neither a definite width nor height, and has no additional contraints, the dimensions of the CSS View Box must be computed as follows:
      1. If the object has an intrinsic width and an intrinsic height, the CSS View Box must have that same height and width.
      2. If the object has only an intrinsic width or intrinsic height, and no intrinsic aspect ratio, the CSS View Box must have that height or width, and the width or height (whichever is missing from the intrinsic dimensions) of the default image sizing area.
      3. If the object has only an intrinsic aspect ratio, the CSS View Box must have that aspect ratio, and additionally be as large as possible without either its height or width exceeding the height or width of the default image sizing area.
      4. Otherwise, the CSS View Box must be the size of the default image sizing area.
   4. If the specified size has additional constraints, the CSS View Box must be sized to satisfy those constraints. (For example, object-fit:contain specifies slightly more complex handling for sizing replaced elements, and background-repeat:round can adjust the size specified in background-size so that the image fits an even number of times into the background positioning area.)

After determining the size of the CSS View Box, CSS positions it within the appropriate area according to any relevant properties, such as object-position or background-position, and asks the object to render itself using the dimensions of the CSS View Box. CSS does not define how objects render when the dimensions of the CSS View Box are different than the object's intrinsic dimensions. The object may adjust itself to match the dimensions of the CSS View Box in some way, or even render itself larger or smaller than the CSS View Box to satisfy sizing constraints of its own.

6.1. Overriding Image Resolutions: the ‘image-resolution’ property

The image resolution is defined as the number of image pixels per unit length, e.g., pixels per inch. Some image formats can record information about the resolution of images. This information can be helpful when determining the actual size of the image in the formatting process. However, the information can also be wrong, in which case it should be ignored. By default, CSS assumes a resolution of one image pixel per CSS ‘px’ unit; however, the ‘image-resolution’ property allows using some other resolution.

The ‘image-resolution’ property specifies the resolution of images. Values have the following meanings:

<resolution>

The value sets the resolution of the image. In combination with ‘from-image’, the specified resolution is only used if the image does not have a resolution.

from-image

The UA must look for the resolution in the image itself. If the image does not have a resolution, the specified <resolution> value is used, or ‘1dppx’ if none is given.

  img { image-resolution: from-image }
  

  img { image-resolution: 300dpi }
  

  img { image-resolution: from-image 300dpi }
  img { image-resolution: 300dpi from-image }
  

6.2. Orienting an Image on the Page: the ‘image-orientation’ property

Images from camera phones, digital cameras or scanners may be encoded sideways. For example, the first row of image data may represent the leftmost or rightmost column of image pixels. Furthermore, often such devices have limited resources, and do not have the capability to rotate the image into an upright orientation. However, this type of device may have internal knowledge or can accept input from its user as to the rotational correction to perform.

The image-orientation property provides a way to specify an "out-of-band" rotation to be applied to image source data. This facility is not intended to specify layout transformations such as arbitrary rotation or flipping the image in the horizontal or vertical direction. It is not needed to correctly orient an image when printing in landscape versus portrait orientation, as that rotation is done as part of layout. It should only be used to correct incorrectly-oriented images.

‘image-orientation’ specifies an orthogonal rotation to be applied to an image before it is laid out. CSS layout processing applies to the image after rotation. This implies, for example:

• The intrinsic height and width are derived from the rotated rather than the original image dimensions;
• The height (width) property applies to the vertical (horizontal) dimension of the image, after rotation.

The following values for the ‘image-orientation’ property apply to an image:

<angle>

Positive values cause the image to be rotated to the right (in a clockwise direction), while negative values cause a rotation to the left. The angular value in degrees, radians or grads is rounded to the nearest cardinal angle. Values half way between cardinal angles, such as 45deg, round forward, in the direction of rotation. Values greater than 360deg or less than -360deg are moduloed to produce a value between 0deg and 360deg. Analogous rules apply for rad and grad unit values.

  img.ninety     { image-orientation: 90deg }
  ...
  <img class="ninety" src=... />
  

6.3. The ‘object-fit’ Property

The ‘object-fit’ property specifies how the contents of a replaced element should be scaled relative to the box established by its used height and width. It also enables scaling a replaced element's contents up to a specified maximum size or down to a specified minimum size while preserving its aspect ratio.

Not all replaced elements can be scaled, but images typically can.

The contents of a replaced element with an intrinsic aspect ratio (which may be derived from intrinsic dimensions) are scaled as follows:

fill

Determine the used ‘height’ and ‘width’ as usual. Scale the content height and width independently so that the edges of the content just meet the edges of the box established by the used ‘height’ and ‘width’.

contain

Determine the used ‘height’ and ‘width’ as usual, except if both ‘height’ and ‘width’ are ‘auto’, and the used value of at least one of ‘max-width’ and ‘max-height’ is not ‘none’, then compute the element's used width and used height as though the intrinsic dimensions of the contents were infinitely large numbers whose ratio is the actual intrinsic ratio of the contents.

Scale the contents of the element, preserving their aspect ratio, to the largest size such that the width of the contents is less than or equal to the used width of the box and the height of the contents is less than or equal to the used height of the box.

cover

Determine the used ‘height’ and ‘width’ as usual, except if both ‘height’ and ‘width’ are ‘auto’, and the used value of at least one of ‘min-width’ and ‘min-height’ is not ‘0’, then compute the used width and used height of the element as though the intrinsic dimensions of the contents were infinitesimally small numbers whose ratio is the actual intrinsic ratio of the contents.

Scale the contents of the element, preserving their aspect ratio, to the smallest size such that the width of the contents is greater than or equal to the used width of the box and the height of the contents is greater than or equal to the height of the box.

The ‘overflow’ property determines how to render parts of the replaced element's content that extend beyond the edges of its box. See the ‘object-position’ property for positioning the object with respect to the element's box.

UAs may support ‘image-fit’ as an alias for ‘object-fit’ when parsing CSS declarations if they need to accommodate existing content that uses the ‘image-fit’ property name.

Note: the ‘object-fit’ property has similar semantics to the fit attribute in [SMIL10].

6.4. The ‘object-position’ Property

The ‘object-position’ property determines the alignment of the replaced element inside its box. The values have the same meaning as the values for the ‘background-position’ property, using the image as the image and the content box as the positioning area. [CSS21]

Note that areas of the box not covered by the replaced element will show the element's background.

UAs may support ‘image-fit’ as an alias for ‘object-fit’ when parsing CSS declarations if they need to accommodate existing content that uses the ‘image-fit’ property name.

7. Serialization

This section describes the serialization of all new properties and value types introduced in this specification, for the purpose of interfacing with the CSS Object Model [CSSOM].

All of these algorithms refer to a variable "s". For each, let s initially be the empty string, run the steps described, and then return s.

Acknowledgments

References

Normative references

[CSS21]

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 8 September 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-CSS2-20090908

[CSS3VAL]

Chris Lilley; Håkon Wium Lie. CSS3 Values and Units. 19 September 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css3-values-20060919

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

[SELECT]

Tantek Çelik; et al. Selectors Level 3. 15 December 2009. W3C Proposed Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/PR-css3-selectors-20091215

Informative references

[CSS3BG]

Bert Bos; Elika J. Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 12 June 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-css3-background-20100612

[CSSOM]

Anne van Kesteren. CSSOM. (forthcoming). W3C Working Draft. (Work in progress.)

[SMIL10]

Philipp Hoschka. Synchronized Multimedia Integration Language (SMIL) 1.0 Specification. 15 June 1998. W3C Recommendation. URL: http://www.w3.org/TR/1998/REC-smil-19980615