Overview.bs

<pre class='metadata'>
Title: CSS Backgrounds Module Level 4
Shortname: css-backgrounds
Level: 4
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-backgrounds-4/
Editor: Bert Bos, W3C, bert@w3.org, w3cid 3343
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Lea Verou, Invited Expert, http://lea.verou.me/about/, w3cid 52258
Editor: Sebastian Zartner, Invited Expert, sebastianzartner@gmail.com, w3cid 64937
Abstract: This module contains the features of CSS relating to the backgrounds of boxes on the page.
Ignored Terms: total width
Warning: Not Ready
</pre>

<pre class="link-defaults">
spec:css-text-4; type:value; text:collapse
spec:css-shapes-2; type:function; text:path()
spec:css-borders-4; type:property; text:border-color
</pre>

<link rel="stylesheet" href="style.css" />

<h2 id="intro">
Introduction</h2>

	<p class="issue">
		This module is currently maintained as a diff against
		the parts related to backgrounds of
		CSS Backgrounds and Borders Module Level 3 [[CSS3BG]].
		We will fold in the text once it's all formatted up and in CR again,
		as this will reduce the effort of keeping them in sync
		(source diffs will be accurate in reflecting the differences).

<h2 id="backgrounds">
Backgrounds</h2>

<h3 id="background-repeat-longhands">
Tiling Images: the 'background-repeat-x', 'background-repeat-y', 'background-repeat-block', and 'background-repeat-inline' properties</h3>

	<pre class="propdef">
		Name: background-repeat-x, background-repeat-y, background-repeat-block, background-repeat-inline
		Value: <<repetition>>#
		Initial: repeat
		Inherited: no
		Percentages: N/A
		Computed value: as specified
		Animation type: discrete
	</pre>

	<pre class="prod">
		<dfn><<repetition>></dfn> = repeat | space | round | no-repeat
	</pre>

	<p>These properties specify whether and how background images are tiled
	along one axis after they have been
	<a href="https://www.w3.org/TR/css-backgrounds-3/#the-background-size">sized</a> and <a href="https://www.w3.org/TR/css-backgrounds-3/#the-background-position">positioned</a>.

	<dl dfn-type=value dfn-for="background-repeat-x, background-repeat-y, background-repeat-block, background-repeat-inline">
		<dt><dfn>repeat</dfn>
		<dd>
			The image is repeated in the given direction as often as needed
			to cover the [=background painting area=].

		<dt><dfn>space</dfn>
		<dd>
			The image is repeated in the given direction as often as will fit
			within the [=background positioning area=] without being
			clipped and then the repeated images are spaced out to fill the area.
			The first and last images touch the edges of the area.
			If the [=background painting area=] is larger than the background positioning area,
			then the pattern repeats to fill the background painting area.
			The value of 'background-position' for this direction is ignored,
			unless there is not enough space for two copies of the image in this direction,
			in which case only one image is placed and
			'background-position' determines its position in this direction.

		<dt><dfn>round</dfn>
		<dd>
			The image is repeated in the given direction as often as will fit
			within the [=background positioning area=].
			If it doesn't fit a whole number of times,
			it is rescaled so that it does.
			See the formula under 'background-size'.
			If the [=background painting area=] is larger than the background positioning area,
			then the pattern repeats to fill the background painting area.

		<dt><dfn>no-repeat</dfn>
		<dd>
			The image is placed once and not repeated in the given direction.
	</dl>

	<p>Unless one of the axes is set to ''no-repeat'', the
	whole background painting area will be tiled, i.e., not just one
	vertical strip and one horizontal strip.

	<div class="example">
		<p style="display:none">Example(s):
		<pre>
			body {
				background: white url("pendant.png");
				background-repeat-y: repeat;
				background-position: center;
			}
		</pre>

		<div class="figure">
			<p><img src="images/bg-repeat.png" alt="A centered background image, with
			copies repeated up and down the border, padding and content
			areas.">

			<p class="caption">The effect of ''repeat'': One copy
			of the background image is centered, and other copies are put above
			and below it to make a vertical band behind the element.
		</div>
	</div>

	<p>See the section <a href="https://www.w3.org/TR/css-backgrounds-3/#layering">“Layering multiple background
	images”</a> for how
	'background-repeat-x',
	'background-repeat-y',
	'background-repeat-block',
	and 'background-repeat-inline'
	interact with other comma-separated background properties
	to form each background image layer.

<h3 id="background-repeat" oldids="the-background-repeat">
Tiling Images Shorthand: the 'background-repeat' property</h3>

	<pre class="propdef">
	Name: background-repeat
	Value: <<repeat-style>>#
	Initial: repeat
	Applies to: all elements
	Inherited: no
	Percentages: N/A
	Computed value: list, each item a pair of keywords, one per dimension
	Animation type: discrete
	</pre>

	<p>This shorthand sets the values for the
	'background-repeat-x' and 'background-repeat-y' longhand properties.
	Where
	<pre class=prod><dfn><<repeat-style>></dfn> = repeat-x | repeat-y | <<repetition>>{1,2}</pre>

	<p>Single values for <<repeat-style>> have the following
	meanings:

	<dl dfn-type=value dfn-for=background-repeat>
	<dt><dfn>repeat-x</dfn>
	<dd>
	Computes to ''repeat no-repeat''.

	<dt><dfn>repeat-y</dfn>
	<dd>
	Computes to ''no-repeat repeat''.

	<dt>''background-repeat-x/repeat''
	<dd>
	Computes to ''repeat repeat''.

	<dt>''background-repeat-x/space''
	<dd>
	Computes to ''space space''

	<dt>''background-repeat-x/round''
	<dd>
	Computes to ''round round''

	<dt>''background-repeat-x/no-repeat''
	<dd>
	Computes to ''no-repeat no-repeat''
	</dl>

	<p>If a <<repeat-style>> value has two keywords, the first
	one is for the horizontal direction, the second for the vertical one.

	<div class=example>
	<p style="display:none">Example(s):
	<pre>
	body {
	background-image: url(dot.png) white;
	background-repeat: space
	}
	</pre>

	<div class=figure>
		<p><img src="images/bg-space.png" alt="Image of an element with a dotted background">

		<p class=caption>The effect of ''background-repeat/space'': the image of a dot is
		tiled to cover the whole background and the images are equally
		spaced.
	</div>
	</div>

	<p>See the section <a href="https://www.w3.org/TR/css-backgrounds-3/#layering">“Layering multiple background
	images”</a> for how 'background-repeat' interacts with other
	comma-separated background properties to form each background image
	layer.

	Issue: Should a <a href="https://lists.w3.org/Archives/Public/www-style/2011Sep/0331.html">'background-repeat: extend'</a> be added?

<h3 id="the-background-position">
Background Positioning: the 'background-position' shorthand property</h3>

	<pre class="propdef shorthand">
		Name: background-position
		Value: <<bg-position>>#
	</pre>

	See [[CSS3BG]] for definition.

	<p>Where
	<pre class=prod><dfn>&lt;bg-position&gt;</dfn> = [
	  [ left | center | right | top | bottom | start | end | <<length-percentage>> ]
	|
	  [ left | center | right | x-start | x-end | <<length-percentage>> ]
	  [ top | center | bottom | y-start | y-end | <<length-percentage>> ]
	|
	  [ center | [ left | right | x-start | x-end ] <<length-percentage>>? ] &amp;&amp;
	  [ center | [ top | bottom | y-start | y-end ] <<length-percentage>>? ]
	|
	  [ center | [ start | end ] <<length-percentage>>? ]
	  [ center | [ start | end ] <<length-percentage>>? ]	]</pre>

	Values have the following meanings:
	<dl>
		<dt>One value
		<dd>
			If only one value is given,
			and that value is ''background-position/start'' or ''background-position/end'',
			then the keyword is duplicated;
			otherwise the second keyword defaults to ''background-position/center''.
			The resulting value is treated as a two-component value.

		<dt>More than one value
		<dd>
			If the value contains a ''background-position/start'' or ''background-position/end'' keyword,
			then the shorthand sets
			'background-position-inline' and 'background-position-block' to the specified values.
			Otherwise
			the shorthand sets
			'background-position-x' and 'background-position-y' to the specified values.

			Issue: Specify the value assignment in more detail. Should expand just like Level 3.
	</dl>

	Issue: Specify what happens to set of properties that are not set. Maybe they're just not set?

<h4 id="background-position-longhands">
Background Positioning Longhands: the 'background-position-x', 'background-position-y', 'background-position-inline', and 'background-position-block' properties</h4>

	Issue: This section is still being worked out. The tricky thing is making all the start/end keywords work sanely.

	<pre class="propdef">
		Name: background-position-x
		Value: [ center | [ [ left | right | x-start | x-end ]? <<length-percentage>>? ]! ]#
		Initial: 0%
		Inherited: no
		Logical property group: background-position
		Percentages: refer to width of background positioning area <em>minus</em> width of background image
		Computed value: A list, each item consisting of: an offset given as a computed <<length-percentage>> value, plus an origin keyword
		Animation type: repeatable list
	</pre>

	This property specifies the background position's horizontal component.
	An omitted origin keyword is assumed to be ''background-position-x/left''.

	<pre class="propdef">
		Name: background-position-y
		Value: [ center | [ [ top | bottom | y-start | y-end ]? <<length-percentage>>? ]! ]#
		Initial: 0%
		Inherited: no
		Logical property group: background-position
		Percentages: refer to height of background positioning area <em>minus</em> height of background image
		Computed value: A list, each item consisting of: an offset given as a computed <<length-percentage>> value, plus an origin keyword
		Animation type: repeatable list
	</pre>

	This property specifies the background position's vertical component.
	An omitted origin keyword is assumed to be ''background-position-y/top''.

	<pre class="propdef">
		Name: background-position-inline
		Value: [ center | [ [ start | end ]? <<length-percentage>>? ]! ]#
		Initial: 0%
		Inherited: no
		Logical property group: background-position
		Percentages: refer to inline-size of background positioning area <em>minus</em> inline-size of background image
		Computed value: A list, each item consisting of: an offset given as a computed <<length-percentage>> value, plus an origin keyword
		Animation type: repeatable list
	</pre>

	This property specifies the background position's inline-axis component.
	An omitted origin keyword is assumed to be ''background-position-inline/start''.

	<pre class="propdef">
		Name: background-position-block
		Value: [ center | [ [ start | end ]? <<length-percentage>>? ]! ]#
		Initial: 0%
		Inherited: no
		Logical property group: background-position
		Percentages: refer to size of background positioning area <em>minus</em> size of background image
		Computed value: A list, each item consisting of: an offset given as a computed <<length-percentage>> value, plus an origin keyword
		Animation type: repeatable list
	</pre>

	This property specifies the background position's block-axis component.
	An omitted origin keyword is assumed to be ''background-position-block/start''.

<h3 id='background-clip'>
Painting Area: the 'background-clip' property</h3>

	<pre class="propdef">
		Name: background-clip
		Value: <<bg-clip>>#
		Initial: border-box
		Inherited: no
		Animation type: repeatable list
	</pre>

	Determines the <dfn export>background painting area</dfn>,
	which determines the area within which the background is painted.
	The syntax of the property is given with

	<pre class=prod>
	<dfn>&lt;bg-clip></dfn> = <<visual-box>> | border-area| text
	</pre>

	Issue: Or should this be defining the <css>-webkit-background-clip</css> property,
	saying that all the values are identical,
	with this additional ''text'' value?

	<dl dfn-type=value dfn-for="background-clip, <bg-clip>">
		<dt><dfn><<visual-box>></dfn>
		<dd>
			The background is painted within (clipped to)
			the specified box of the element.

		<dt><dfn>text</dfn>
		<dd>
			The background is painted within (clipped to)
			the intersection of the border box
			and the geometry of the text in the element and its in-flow and floated descendants.

		<dt><dfn>border-area</dfn></dt>
		<dd>
			The background is clipped to the area painted by the border, taking 'border-width' and 'border-style' into account but ignoring any transparency introduced by 'border-color'.
		</dd>
	</dl>

<h3 id='background-layers'>
Background Image Layers: the 'background-tbd' shorthand property</h3>

	<pre class="propdef">
		Name: background-tbd
		Value: <<bg-layer>>#
		Initial: see individual properties
		Applies to: all elements
		Inherited: no
		Percentages: see individual properties
		Computed value: see individual properties
		Animation type: see individual properties
	</pre>

	<p>The 'background-tbd' property is a [=shorthand property=]
	that sets all the same properties as the 'background' shorthand
	except for 'background-color',
	allowing authors to easily declare and position background images
	while letting 'background-color' cascade through independently.

	Issue:
		The name of this property is discussed in
		<a href="https://github.com/w3c/csswg-drafts/issues/9083">issue 9083</a>.

	<div class="example" id="background-layer-example">
		This example sets two background layers later in the cascade.
		By using 'background-tbd', the previously set 'background-color'
		won't be overridden.

		<pre class="lang-css">
		p {
			background-color: green;
		}

		p {
			background-tbd:
				url(a.png) top left,
				url(b.png) top left no-repeat;
		}
		</pre>
	</div>

	<div class="invalid example" id="invalid-background-layer-example">
		This example tries to set the background color in addition to
		the background image. But for that to work,
		'background' needs to be used instead of 'background-tbd'.
		So the 'background-tbd' declaration will be dropped.

		<pre class="lang-css">
		p {
			background: url(pass.png) green;   /* valid */
			background-tbd: url(fail.png) red; /* invalid */
		}
		</pre>
	</div>

<h2 id="changes">
Changes</h2>

<h3 id="level-changes">
Additions since [[CSS3BG]]</h3>

	* turned 'background-position' into a shorthand and added physical and logical longhands
	* added logical keywords to <<bg-position>>
	* added 'background-clip'
	* added 'background-tbd'
	* added 'background-repeat-*' longhands

<h2 id="acknowledgments">
Acknowledgments</h2>

	<p>In addition to the many contributors to the [[CSS1]], [[CSS21]],
	and [[CSS3BG]] predecessors to this module,
	the editors would like to thank
	Tab Atkins,
	and Håkon Wium Lie
	for their suggestions and feedback specifically for this Level 4.

<h2 class=no-num id=privacy>Privacy Considerations</h2>

No new privacy considerations have been reported on this specification.

<h2 class=no-num id=security>Security Considerations</h2>

No new security considerations have been reported on this specification.