<pre class='metadata'>

Title: CSS Values and Units Module Level 5

Group: CSSWG

Shortname: css-values

Level: 5

Status: ED

Work Status: Exploring

ED: https://drafts.csswg.org/css-values-5/

TR: https://www.w3.org/TR/css-values-5/

Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199

Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400

Editor: Miriam E. Suzanne, Invited Expert, http://miriamsuzanne.com/contact, w3cid 117151

Abstract: This CSS module describes the common values and units that CSS properties accept and the syntax used for describing them in CSS property definitions.

Ignored Terms: <spacing-limit>, containing block, property, <wq-name>

Ignored Vars: Cn+1, n

Inline Github Issues: no

Default Highlight: css

Status Text: <strong>This spec is in the early exploration phase. Feedback is welcome, and and major breaking changes are expected.</strong>

Include MDN Panels: yes

WPT Path Prefix: css/css-values/

</pre>

<pre class='link-defaults'>

spec:css-color-4; type:property; text:color

spec:css-values-4; type: dfn;

text: determine the type of a calculation

text: keyword

text: identifier

spec:selectors-4; type: dfn; text: selector

spec:css-conditional-5;

type:type;

text:<size-feature>

text:<container-name>

text:<style-query>

type:dfn; text:container feature

type:at-rule; text:@container

spec:css-mixins-1; type:dfn; text:custom function

spec:css-properties-values-api; type:dfn; text: supported syntax component names

spec:html; type:element; text:link

spec:infra; type:dfn;

text:list

text:user agent

</pre>

<style>

code, small { white-space: nowrap }

pre.value { font: inherit; white-space: pre-wrap; margin: 0; padding: 0; }

#propvalues td { text-align: right; }

#propvalues td + td { text-align: left; }

dt + dt::before { content: ", "; }

dl:not(.switch) dt { display: inline; }

td > small { display: block; }

</style>

<style>

/* Put nice boxes around each algorithm. */

[data-algorithm]:not(.heading) {

padding: .5em;

border: thin solid #ddd; border-radius: .5em;

margin: .5em calc(-0.5em - 1px);

}

[data-algorithm]:not(.heading) > :first-child {

margin-top: 0;

}

[data-algorithm]:not(.heading) > :last-child {

margin-bottom: 0;

}

[data-algorithm] [data-algorithm] {

margin: 1em 0;

}

</style>

<h2 id="intro">

Introduction</h2>

ISSUE: <strong>This is a diff spec against <a href="https://www.w3.org/TR/css-values-4/">CSS Values and Units Level 4</a>.</strong>

<h3 id="placement">

Module Interactions</h3>

This module extends [[CSS-VALUES-4]]

which replaces and extends the data type definitions in [[!CSS21]] sections

<a href="https://www.w3.org/TR/CSS21/about.html#value-defs">1.4.2.1</a>,

<a href="https://www.w3.org/TR/CSS21/syndata.html#values">4.3</a>,

and <a href="https://www.w3.org/TR/CSS21/aural.html#aural-intro">A.2</a>.

<h2 id="textual-values">

Textual Data Types</h2>

See [[css-values-4#textual-values]].

<!-- Big Text: syntax

███▌ █ ▐▌ █ █▌ █████▌ ███▌ █ █

█▌ █▌ ▐▌ █ █▌ █▌ █▌ ▐█ ▐█ █ █

█▌ █ ▐▌ ██▌ █▌ █▌ █▌ █▌ █ █

███▌ ▐▌█ █▌▐█ █▌ █▌ █▌ █▌ █

█▌ █▌ █▌ ██▌ █▌ █████▌ █ █

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █ █

███▌ █▌ █▌ ▐▌ █▌ █▌ █▌ █ █

-->

<h2 id=value-defs>

Value Definition Syntax</h2>

See [[css-values-4#value-defs]].

Additionally,

<ol>

<li value=5>Boolean combinations of a conditional notation.

These are written using the <<boolean-expr[]>> notation,

and represent recursive expressions of boolean logic

using keywords and parentheses,

applied to the grammar specified in brackets,

e.g. <<boolean-expr[ ( &lt;media-feature&gt; ) ]>> to express [=media queries=].

</ol>

<h3 id=component-functions>

Functional Notation Definitions</h3>

See [[css-values-4#component-functions]].

<h4 id=component-function-commas>

Commas in Function Arguments</h4>

[=Functional notation=] often uses commas

to separate parts of its internal grammar,

and occasionally other syntax

(such as <code>:</code> or <code>;</code> in ''if()'').

However, some functions

(such as ''mix()'')

allow values that, themselves,

could contain these argument-separating tokens.

These values

(currently <<whole-value>>, <<declaration-value>>, and <<any-value>>)

are <dfn export>free-form productions</dfn>.

To accommodate these sorts of grammars unambiguously,

the [=free-form productions=] can be optionally wrapped in curly braces {}.

These braces are syntactic, not part of the actual value,

and only serve to explicitly indicate the bounds of the production.

A [=free-form production=] can either

(after optional whitespace)

start with a <<{-token>>, or not:

: If it does not start with a "{" token

::

The production does not match any top-level commas or {} blocks.

(The production stops parsing at that point,

so the comma or {} block is matched by the next grammar term instead;

probably the function's own argument-separating comma.)

Individual usages of the production can define additional tokens

that are similarly restricted from matching at the top-level.

: If it does start with a "{" token

::

The production matches just the {} block that the "{" token opens.

It represents the <em>contents</em> of that block,

ignoring the {} block wrapper itself.

Note: General restrictions defined for a particular [=free-form production=],

like <<declaration-value>> not matching <<semicolon-token>>s,

apply regardless of whether it's {}-wrapped or not.

<div class="example">

For example, the grammar of the ''random-item()'' function is:

<pre>

random-item( <<random-key>>, [<<declaration-value>>?]# )

</pre>

The ''#'' indicates comma-separated repetitions,

so randomly choosing between three keywords

would be written as normal for functions,

like:

<pre>

font-family: random-item(--x, serif, sans-serif, monospace);

</pre>

However, sometimes the values you want to choose between

need to include commas.

When this is the case,

wrapping the values in {}

allows their commas to be distinguished

from the function's argument-separating commas:

<pre>

font-family: random-item(--x, {Times, serif}, {Arial, sans-serif}, {Courier, monospace});

</pre>

This randomly chooses one of three font-family lists:

either ''Times, serif'', or ''Arial, sans-serif'', or ''Courier, monospace''.

This is not all-or-nothing;

you can use {} around <em>some</em> arguments that need it,

while leaving others bare when they don't need it.

You are also allowed to use {} around a value when it's not strictly required.

For example:

<pre>

font-family: random-item(--x, {Times, serif}, sans-serif, {monospace});

</pre>

This represents choosing between three font-family lists:

either ''Times, serif'', or ''sans-serif'', or ''monospace''.

However, this {}-wrapping is <em>only</em> allowed for some function arguments--

those defined as [=free-form productions=].

It's not valid for any other productions;

if you use {} around other function arguments,

it'll just fail to match the function's grammar

and become invalid.

For example, the following is <strong>invalid</strong>:

<pre>

background-image: linear-gradient(to left, {red}, magenta);

</pre>

</div>

Note: Because {} wrappers are allowed even when not explicitly required,

they can be used defensively around values

when the author isn't sure if they'll end up containing commas or not,

due to [=arbitrary substitution functions=] like ''var()''.

For example, <l property>''font-family: random-item(--x, {var(--list1)}, monospace)''</l>

will work correctly

regardless of whether the ''--list1'' custom property

contains a comma-separated list or not.

[=Functional notations=] are serialized without {} wrappers whenever possible.

The following generic productions are [=free-form productions=]:

* <<any-value>>

* <<whole-value>>

* <<declaration-value>>

For legacy compat reasons,

the <<declaration-value>> defined for the fallback value of ''var()''

is a <dfn export>non-strict free-form production</dfn>.

It ignores the rules restricting what it can contain

when it does not start with a "{" token:

it is allowed to contain commas and {} blocks.

It still follows the standard [=free-form production=] rules

when it <em>does</em> start with a "{" token, however:

the fallback is just the contents of the {} block,

and doesn't include the {} wrapper itself.

Other contexts <em>may</em> define that they use [=non-strict free-form productions=],

but it <em>should</em> be avoided unless necessary.

<h3 id=boolean>

Boolean Expression Multiplier <<boolean-expr[]>></h3>

Several contexts

(such as ''@media'', ''@supports'', ''if()'', ...)

specify conditions,

and allow combining those conditions with boolean logic (and/or/not/grouping).

Because they use the same non-trivial recursive syntax structure,

the special <dfn type><<boolean-expr>></dfn> production represents this pattern generically.

The <<boolean-expr[]>> notation wraps another value type in the square brackets within it,

e.g. &lt;boolean[ &lt;test&gt; ]&gt;,

and represents that value type alone as well as

boolean combinations

using the ''not'', ''and'', and ''or'' keywords

and grouping parenthesis.

It is formally equivalent to:

<xmp class=prod>

<boolean-expr[ <test> ]> = not <boolean-expr-group> | <boolean-expr-group>

[ [ and <boolean-expr-group> ]*

| [ or <boolean-expr-group> ]* ]

<boolean-expr-group> = <test> | ( <boolean-expr[ <test> ]> ) | <general-enclosed>

</xmp>

The <<boolean-expr[]>> production represents a true, false, or unknown value.

Its value is resolved using 3-value Kleene logic,

with top-level unknown values

(those not directly nested inside the grammar of another <<boolean-expr[]>>)

resolving to false unless otherwise specified;

see [[#boolean-logic]] for details.

<div class=example>

For example, the ''@container'' rule allows a wide variety of tests:

including size queries, style queries, and scroll-state queries.

All of these are arbitrarily combinable with boolean logic.

Using <<boolean-expr[]>>, the grammar for an ''@container'' query

could be written as:

<xmp class=prod>

<container-query> = <boolean-expr[ <cq-test> ]>

<cq-test> = (<size-query>) | style( <style-query> ) | scroll-state( <scroll-state-query> )

<size-query> = <boolean-expr[ ( <size-feature> ) ]> | <size-feature>

<style-query> = <boolean-expr[ ( <style-feature> ) ]> | <style-feature>

<scroll-state-query> = <boolean-expr[ ( <scroll-state-feature> ) ]> | <scroll-state-feature>

</xmp>

</div>

The <<general-enclosed>> branch of the logic allows for future compatibility--

unless otherwise specified new expressions in an older UA

will be parsed and considered “unknown”,

rather than invalidating the production.

For consistency with that allowance,

the <css>&lt;test></css> term in a <<boolean-expr[]>>

should be defined to match <<general-enclosed>>.

<h3 id=css-syntax>

Specifying CSS Syntax in CSS: the <<syntax>> type</h3>

Some features in CSS,

such as the ''attr()'' function

or [=registered custom properties=],

allow you to specify how <em>another</em> value is meant to be parsed.

This is declared via the <<syntax>> production,

which resembles a limited form of the CSS [=value definition syntax=]

used in specifications to define CSS features,

and which represents a [=syntax definition=]:

<pre class="prod def" nohighlight>

<dfn><<syntax>></dfn> = '*' | <<syntax-component>> [ <<syntax-combinator>> <<syntax-component>> ]* | <<syntax-string>>

<dfn><<syntax-component>></dfn> = <<syntax-single-component>> <<syntax-multiplier>>?

| '<' transform-list '>'

<dfn><<syntax-single-component>></dfn> = '<' <<syntax-type-name>> '>' | <<ident>>

<dfn><<syntax-type-name>></dfn> = angle | color | custom-ident | image | integer

| length | length-percentage | number

| percentage | resolution | string | time

| url | transform-function

<dfn><<syntax-combinator>></dfn> = '|'

<dfn><<syntax-multiplier>></dfn> = [ '#' | '+' ]

<dfn><<syntax-string>></dfn> = <<string>>

</pre>

A <<syntax-component>> consists of either

a <<syntax-type-name>> between &lt;&gt; (angle brackets),

which maps to one of the [=supported syntax component names=],

or an <<ident>>, which represents any [=keyword=].

Additionally,

a <<syntax-component>> may contain a [[css-properties-values-api-1#multipliers|multiplier]],

which indicates a [=list=] of values.

Note: This means that <code>&lt;length&gt;</code>

and <code>length</code> are two different types:

the former describes a <<length>>,

whereas the latter describes a [=keyword=] <code>length</code>.

Multiple <<syntax-component>>s may be [[css-properties-values-api-1#combinator|combined]]

with a <code>|</code> <<delim-token>>,

causing the syntax components to be matched

against a value

in the specified order.

<div class='example'>

<xmp class='lang-css'>

<percentage> | <number> | auto

</xmp>

The above, when parsed as a <<syntax>>,

would accept <<percentage>> values,

<<number>> values,

as well as the keyword <code>auto</code>.

</div>

<div class='example'>

<xmp class='lang-css'>

red | <color>

</xmp>

The [=syntax definition=] resulting from the above <<syntax>>,

when used as a grammar for [=parse|parsing=],

would match an input <code>red</code> as an [=identifier=],

but would match an input <code>blue</code> as a <<color>>.

</div>

The <code>*</code> <<delim-token>> represents the [=universal syntax definition=].

The <code>&lt;transform-list&gt;</code> production

is a convenience form equivalent to <code>&lt;transform-function&gt;+</code>.

<span class=note>Note that <code>&lt;transform-list&gt;</code> may not

be followed by a <<syntax-multiplier>>.</span>

[=Whitespace=] is not allowed

between the angle bracket <<delim-token>>s (<code>&lt;</code> <code>&gt;</code>)

and the <<syntax-type-name>> they enclose,

nor is [=whitespace=] allowed to precede a <<syntax-multiplier>>.

Note: The [=whitespace=] restrictions also apply to <code>&lt;transform-list&gt;</code>.

A <<syntax-string>> is a <<string>>

whose value successfully [=CSS/parses=] as a <<syntax>>,

and represents the same value as that <<syntax>> would.

Note: <<syntax-string>> mostly exists for historical purposes;

before <<syntax>> was defined,

the ''@property'' rule used a <<string>> for this purpose.

<h4 id=parse-syntax>

Parsing as <<syntax>></h4>

The purpose of a <<syntax>>

is usually to specify how to parse another value

(such as the value of a [=registered custom property=],

or an attribute value in ''attr()'').

However, the generic [=CSS/parse something according to a CSS grammar=] algorithm

returns an unspecified internal structure,

since parse results might be ambiguous

and need further massaging.

To avoid these issues and get a well-defined result,

use [=parse with a <syntax>=]:

<div algorithm>

To <dfn export>parse with a <<syntax>></dfn>

given a [=string=] or [=list=] or [=CSS/component values=] |values|,

a <<syntax>> value |syntax|,

and optionally an element |el| for context,

perform the following steps.

It returns either CSS values,

or the [=guaranteed-invalid value=].

1. [=Parse a list of component values=] from |values|,

and let |raw parse| be the result.

2. If |el| was given,

[=substitute arbitrary substitution functions=] in |raw parse|,

and set |raw parse| to that result.

3. [=CSS/parse=] |values| according to |syntax|,

with a ''*'' value treated as <code><<declaration-value>>?</code>,

and let |parsed result| be the result.

If |syntax| used a ''|'' combinator,

let |parsed result| be the parse result from the first matching clause.

4. If |parsed result| is failure,

return the [=guaranteed-invalid value=].

5. Assert: |parsed result| is now a well-defined list of one or more CSS values,

since each branch of a <<syntax>> defines an unambiguous parse result

(or the ''*'' syntax is unambiguous on its own).

6. Return |parsed result|.

</div>

Note: This algorithm does not resolved the parsed values

into [=computed values=];

the context in which the value is used will usually do that already,

but if not,

the invoking algorithm will need to handle that on its own.

<h2 id="level-4-extensions">

Extensions to Level 4 Value Types</h2>

See <a href="https://www.w3.org/TR/css-values-4/">CSS Values and Units Level 4</a>.

<!-- Big Text: url

█▌ █▌ ████▌ █▌

█▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌

█▌ █▌ ████▌ █▌

█▌ █▌ █▌▐█ █▌

█▌ █▌ █▌ ▐█ █▌

███▌ █▌ █▌ █████

-->

<h3 id="urls">

Resource Locators: the <<url>> type</h3>

See [[css-values-4#urls]].

<wpt>

urls/empty.html

urls/fragment-only.html

urls/resolve-relative-to-base.sub.html

urls/resolve-relative-to-stylesheet.html

inline-cache-base-uri-cssom.html

inline-cache-base-uri.html

</wpt>

<h4 id='request-url-modifiers'>

Request URL Modifiers</h4>

<dfn><<request-url-modifier>></dfn>s are <<url-modifier>>s

that affect the <<url>>’s resource [=/request=]

by applying associated [=URL request modifier steps=].

See [[css-values-4#url-processing]].

This specification defines the following <<request-url-modifier>>s:

<pre class=prod>

<<request-url-modifier>> = <<cross-origin-modifier>> | <<integrity-modifier>> | <<referrer-policy-modifier>>

<<cross-origin-modifier>> = cross-origin(anonymous | use-credentials)

<<integrity-modifier>> = integrity(<<string>>)

<<referrer-policy-modifier>> = referrer-policy(no-referrer | no-referrer-when-downgrade | same-origin | origin | strict-origin | origin-when-cross-origin | strict-origin-when-cross-origin | unsafe-url)

</pre>

<dl dfn-for="<request-url-modifier>">

<dt><dfn><<cross-origin-modifier>></dfn> = <dfn function lt="cross-origin()">cross-origin</dfn>(<dfn value>anonymous</dfn> | <dfn value>use-credentials</dfn>)

<dd>

The [=URL request modifier steps=] for this modifier given [=/request=] |req| are:

1. Set |req|'s [=request/mode=] to "cors".

2. If the given value is ''use-credentials'',

set |req|'s [=request/credentials mode=] to "include".

3. Otherwise, set |req|'s [=request/credentials mode=] to "same-origin".

<dt><dfn><<integrity-modifier>></dfn> = <dfn function lt="integrity()">integrity</dfn>(<<string>>)

<dd>

The [=URL request modifier steps=] for this modifier given [=/request=] |req|

are to set [=/request=]'s [=request/integrity metadata=]

to the given <<string>>.

<dt><dfn><<referrer-policy-modifier>></dfn> = <dfn function lt="referrer-policy()">referrer-policy</dfn>(<dfn value>no-referrer</dfn> | <dfn value>no-referrer-when-downgrade</dfn> | <dfn value>same-origin</dfn> | <dfn value>origin</dfn> | <dfn value>strict-origin</dfn> | <dfn value>origin-when-cross-origin</dfn> | <dfn value>strict-origin-when-cross-origin</dfn> | <dfn value>unsafe-url</dfn>)

<dd>

The [=URL request modifier steps=] for this modifier given [=/request=] |req|

are to set [=/request=]'s [=request/referrer policy=]

to the {{ReferrerPolicy}} that matches the given value.

</dl>

<div algorithm>

To <dfn export>apply request modifiers from URL value</dfn>

given a [=/request=] |req|

and a <<url>> |url|,

call the [=URL request modifier steps=] for |url|'s <<request-url-modifier>>s in sequence

given |req|.

</div>

<wpt>

urls/cross-origin/url-font-cross-origin-anonymous-negative.sub.html

urls/cross-origin/url-font-cross-origin-anonymous.sub.html

urls/cross-origin/url-font-cross-origin-use-credentials-negative.sub.html

urls/cross-origin/url-font-cross-origin-use-credentials.sub.html

urls/cross-origin/url-image-cross-origin-anonymous-negative.sub.html

urls/cross-origin/url-image-cross-origin-anonymous.sub.html

urls/cross-origin/url-image-cross-origin-use-credentials-negative.sub.html

urls/cross-origin/url-image-cross-origin-use-credentials.sub.html

urls/cross-origin/url-image-set-cross-origin-anonymous-negative.sub.html

urls/cross-origin/url-image-set-cross-origin-anonymous.sub.html

urls/cross-origin/url-import-cross-origin-anonymous-negative.sub.html

urls/cross-origin/url-import-cross-origin-anonymous.sub.html

urls/cross-origin/url-import-cross-origin-use-credentials-negative.sub.html

urls/cross-origin/url-import-cross-origin-use-credentials.sub.html

urls/cross-origin/url-svg-filter-cross-origin-anonymous-negative.sub.html

urls/cross-origin/url-svg-filter-cross-origin-anonymous.sub.html

urls/cross-origin/url-svg-filter-cross-origin-use-credentials-negative.sub.html

urls/cross-origin/url-svg-filter-cross-origin-use-credentials.sub.html

urls/integrity/url-font-integrity-negative.sub.html

urls/integrity/url-font-integrity.sub.html

urls/integrity/url-image-integrity-negative.sub.html

urls/integrity/url-image-integrity.sub.html

urls/integrity/url-import-integrity-negative.sub.html

urls/integrity/url-import-integrity.sub.html

urls/integrity/url-svg-filter-integrity-negative.sub.html

urls/integrity/url-svg-filter-integrity.sub.html

urls/referrer-policy/no-referrer-when-downgrade/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/no-referrer-when-downgrade/url-image-referrer-policy-same-origin.html

urls/referrer-policy/no-referrer/url-font-referrer-policy.sub.html

urls/referrer-policy/no-referrer/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/no-referrer/url-image-referrer-policy-external-stylesheet.html

urls/referrer-policy/no-referrer/url-image-referrer-policy-same-origin.html

urls/referrer-policy/no-referrer/url-image-set-referrer-policy.sub.html

urls/referrer-policy/no-referrer/url-import-referrer-policy.html

urls/referrer-policy/no-referrer/url-svg-filter-referrer-policy.sub.html

urls/referrer-policy/origin-when-cross-origin/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/origin-when-cross-origin/url-image-referrer-policy-same-origin.html

urls/referrer-policy/origin/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/origin/url-image-referrer-policy-external-stylesheet.html

urls/referrer-policy/origin/url-image-referrer-policy-same-origin.html

urls/referrer-policy/same-origin/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/same-origin/url-image-referrer-policy-same-origin.html

urls/referrer-policy/strict-origin-when-cross-origin/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/strict-origin-when-cross-origin/url-image-referrer-policy-same-origin.html

urls/referrer-policy/strict-origin/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/strict-origin/url-image-referrer-policy-same-origin.html

urls/referrer-policy/unsafe-url/url-image-referrer-policy-cross-origin.html

urls/referrer-policy/unsafe-url/url-image-referrer-policy-external-stylesheet.html

urls/referrer-policy/unsafe-url/url-image-referrer-policy-same-origin.html

urls/url-request-modifiers-computed.sub.html

urls/url-request-modifiers-font-face-parsing.html

urls/url-request-modifiers-import-parsing.sub.html

urls/url-request-modifiers-invalid.sub.html

urls/url-request-modifiers-serialize.sub.html

</wpt>

<!-- Big Text: position

████▌ ███▌ ███▌ ████ █████▌ ████ ███▌ █ █▌

█▌ █▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ ██▌ █▌

████▌ █▌ █▌ ███▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌▐█ █▌

█▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ ██▌

█▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ █▌

█▌ ███▌ ███▌ ████ █▌ ████ ███▌ █▌ ▐▌

-->

<h3 id="position">

2D Positioning: the <<position>> type</h3>

The <dfn><<position>></dfn> value specifies the position

of an [=alignment subject=] (e.g. a background image)

inside an [=alignment container=] (e.g. its [=background positioning area=])

as a pair of offsets between the specified edges

(defaulting to the left and top).

Its syntax is:

<pre class=prod>

<<position>> = <<position-one>> | <<position-two>> | <<position-four>>

<dfn><<position-one>></dfn> = [

left | center | right | top | bottom |

x-start | x-end | y-start | y-end |

block-start | block-end | inline-start | inline-end |

<<length-percentage>>

]

<dfn><<position-two>></dfn> = [

[ left | center | right | x-start | x-end ] &&

[ top | center | bottom | y-start | y-end ]

|

[ left | center | right | x-start | x-end | <<length-percentage>> ]

[ top | center | bottom | y-start | y-end | <<length-percentage>> ]

|

[ block-start | center | block-end ] &&

[ inline-start | center | inline-end ]

|

[ start | center | end ]{2}

]

<dfn><<position-four>></dfn> = [

[ [ left | right | x-start | x-end ] <<length-percentage>> ] &&

[ [ top | bottom | y-start | y-end ] <<length-percentage>> ]

|

[ [ block-start | block-end ] <<length-percentage>> ] &&

[ [ inline-start | inline-end ] <<length-percentage>> ]

|

[ [ start | end ] <<length-percentage>> ]{2}

]

</pre>

If only one value is specified (<<position-one>>),

the second value is assumed to be ''center''.

If two values are given (<<position-two>>),

a <<length-percentage>> as the first value represents

the horizontal position as the offset between

the left edges of the [=alignment subject=] and [=alignment container=],

and a <<length-percentage>> as the second value represents

the vertical position as an offset between their top edges.

If both keywords are one of ''<position>/start'' or ''<position>/end'',

the first one represents the [=block axis=]

and the second the [=inline axis=].

Note: A pair of axis-specific keywords can be reordered,

while a combination of keyword and length or percentage cannot.

So ''center left'' or ''inline-start block-end'' is valid,

while ''50% left'' is not.

''<position>/start'' and ''<position>/end'' aren't axis-specific,

so ''start end'' and ''end start'' represent two different positions.

If four values are given (<<position-four>>)

then each <<length-percentage>> represents an offset between

the edges specified by the preceding keyword.

For example, ''background-position: bottom 10px right 20px''

represents a ''10px'' vertical offset up from the bottom edge

and a ''20px'' horizontal offset leftward from the right edge.

Positive values represent an offset <em>inward</em>

from the edge of the [=alignment container=].

Negative values represent an offset <em>outward</em>

from the edge of the [=alignment container=].

<div class="example">

The following declarations give the stated (horizontal, vertical)

offsets from the top left corner:

<pre>

background-position: left 10px top 15px; /* 10px, 15px */

background-position: left top ; /* 0px, 0px */

background-position: 10px 15px; /* 10px, 15px */

background-position: left 15px; /* 0px, 15px */

background-position: 10px top ; /* 10px, 0px */

</pre>

</div>

<div class=example>

<<position>>s can also be relative to other corners than the top left.

For example, the following puts the background image

10px from the bottom and 3em from the right:

<pre>background-position: right 3em bottom 10px</pre>

</div>

The [=computed value=] of a <<position>> is

a pair of offsets (horizontal and vertical),

each given as a computed <<length-percentage>> value,

representing the distance between the left edges and top edges (respectively)

of the [=alignment subject=] and [=alignment container=].

<dl dfn-for="<position>" dfn-type=value>

<dt><dfn><<length-percentage>></dfn>

<dd>

A <<length-percentage>> value specifies the size of the offset

between the specified edges of the [=alignment subject=] and [=alignment container=].

For example, for ''background-position: 2cm 1cm'',

the top left corner of the background image is placed

2cm to the right and 1cm below

the top left corner of the [=background positioning area=].

A <<percentage>> for the horizontal offset is relative to

(<var ignore>width of [=alignment container=]</var> - <var ignore>width of [=alignment subject=]</var>).

A <<percentage>> for the vertical offset is relative to

(<var ignore>height of [=alignment container=]</var> - <var ignore>height of [=alignment subject=]</var>).

<div class=example>

For example, with a value pair of ''0% 0%'',

the upper left corner of the [=alignment subject=] is aligned with

the upper left corner of the [=alignment container=]

A value pair of ''100% 100%'' places

the lower right corner of the [=alignment subject=]

in the lower right corner of the [=alignment container=].

With a value pair of ''75% 50%'',

the point 75% across and 50% down the [=alignment subject=]

is to be placed at the point 75% across and 50% down the [=alignment container=].

<figure>

<img src="images/bg-pos.png" width="397" height="269"

alt="Diagram of image position within element"

>

<figcaption>

Diagram of the meaning of ''background-position: 75% 50%''.

</figcaption>

</figure>

</div>

<dt><dfn>top</dfn>

<dt><dfn>right</dfn>

<dt><dfn>bottom</dfn>

<dt><dfn>left</dfn>

<dd>

Offsets the top/left/right/bottom edges (respectively)

of the [=alignment subject=] and [=alignment container=]

by the specified amount (defaulting to ''0%'')

in the corresponding axis.

<dt><dfn>y-start</dfn>

<dt><dfn>y-end</dfn>

<dt><dfn>x-start</dfn>

<dt><dfn>x-end</dfn>

<dd>

Computes the same as the physical edge keyword

corresponding to the [=start=]/[=end=] side

in the [=y-axis|y=]/[=x-axis|x=] axis.

<dt><dfn>block-start</dfn>

<dt><dfn>block-end</dfn>

<dt><dfn>inline-start</dfn>

<dt><dfn>inline-end</dfn>

<dd>

Computes the same as the physical edge keyword

corresponding to the [=start=]/[=end=] side

in the [=block axis|block=]/[=inline axis|inline=] axis.

<dt><dfn>center</dfn>

<dd>

Computes to a ''50%'' offset in the corresponding axis.

</dl>

Unless otherwise specified, the [=flow-relative=] keywords are resolved

according to the [=writing mode=] of the element on which the value is specified.

Note: The 'background-position' property also accepts a three-value syntax.

This has been disallowed generically because it creates parsing ambiguities

when combined with other length or percentage components in a property value.

ISSUE(9690): Need to define how this syntax would expand to the longhands of 'background-position'

if e.g. ''var()'' is used for some (or all) of the components.

<h4 id="position-parsing">

Parsing <<position>></h4>

When specified in a grammar alongside other keywords, <<length>>s, or <<percentage>>s,

<<position>> is <em>greedily</em> parsed;

it consumes as many components as possible.

<div class=example>

For example,

'transform-origin' defines a 3D position

as (effectively) ''<<position>> <<length>>?''.

A value such as ''left 50px''

will be parsed as a 2-value <<position>>,

with an omitted z-component;

on the other hand,

a value such as ''top 50px''

will be parsed as a single-value <<position>>

followed by a <<length>>.

</div>

<h4 id="position-serialization">

Serializing <<position>></h4>

When serializing the [=specified value=] of a <<position>>:

<dl class=switch>

<dt>If only one component is specified:

<dd>

* The implied <a value spec="css-backgrounds-3">center</a> keyword is added,

and a 2-component value is serialized.

<dt>If two components are specified:

<dd>

* Keywords are serialized as keywords.

* <<length-percentage>>s are serialized as <<length-percentage>>s.

* Components are serialized horizontal first, then vertical.

<dt>If four components are specified:

<dd>

* Keywords and offsets are both serialized.

* Components are serialized horizontal first, then vertical;

alternatively [=block-axis=] first, then [=inline-axis=].

</dl>

Note: <<position>> values are never serialized as a single value,

even when a single value would produce the same behavior,

to avoid causing parsing ambiguities in some grammars

where a <<position>> is placed next to a <<length>>,

such as 'transform-origin'.

The [=computed value=] of a <<position>>

is serialized as a pair of <<length-percentage>>s

representing offsets from the left and top edges, in that order.

<h4 id="combine-positions">

Combination of <<position>></h4>

<l spec=css-values-4>[=Interpolation=]</l> of <<position>> is defined as

the independent interpolation of each component (x, y)

normalized as an offset from the top left corner

as a <<length-percentage>>.

<l spec=css-values-4>[=value addition|Addition=]</l> of <<position>> is likewise defined as

the independent <l spec=css-values-4>[=value addition|addition=]</l> each component (x, y)

normalized as an offset from the top left corner

as a <<length-percentage>>.

<!-- Big Text: progress

████▌ ████▌ ███▌ ███▌ ████▌ █████▌ ███▌ ███▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

████▌ ████▌ █▌ █▌ █▌ ██▌ ████▌ ████ ███▌ ███▌

█▌ █▌▐█ █▌ █▌ █▌ █▌ █▌▐█ █▌ █▌ █▌

█▌ █▌ ▐█ █▌ █▌ █▌ █▌ █▌ ▐█ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ ███▌ ███▌ █▌ █▌ █████▌ ███▌ ███▌

-->

<h2 id="progress" oldids="progress-func">

Interpolation Progress Calculations: the ''progress()'' notation</h2>

<wpt>

progress-computed.html

progress-invalid.html

progress-serialize.html

</wpt>

The <dfn>progress()</dfn> [=functional notation=]

represents the proportional distance

of a given value (the <dfn noexport>progress value</dfn>)

from one value (the <dfn noexport>progress start value</dfn>)

to another value (the <dfn noexport>progress end value</dfn>),

each represented as a [=calculation=].

It is a [=math function=],

and can be input into other calculations

such as a [=math function=]

or a [=mix notation=].

The syntax of ''progress()'' is:

<pre class=prod>

<<progress()>> = progress(no-clamp? <<calc-sum>>, <<calc-sum>>, <<calc-sum>>)

</pre>

where the first, second, and third <<calc-sum>> values represent

the [=progress value=], [=progress start value=], and [=progress end value=],

respectively.

If <dfn value for="progress()">no-clamp</dfn> is present,

the ''progress()'' function can potentially resolve to any number;

if omitted (the default),

the return value is clamped to the range [0, 1].

The argument [=calculations=] can resolve to any <<number>>, <<dimension>>, or <<percentage>>,

but must have a [=consistent type=]

or else the function is invalid.

<div algorithm>

The result of ''progress()'' is a <<number>>

[=made consistent=] with the [=consistent type=] of its arguments,

resolved by <dfn noexport lt="calculate a progress function">calculating a progress function</dfn> as follows:

: If the [=progress start value=] and [=progress end value=] are different values

:: <code>([=progress value=] - [=progress start value=]) / ([=progress end value=] - [=progress start value=])</code>,

clamped to the [0,1] range if ''no-clamp'' is not specified.

: If the [=progress start value=] and [=progress end value=] are the same value

:: 0 if ''no-clamp'' is not specified.

Otherwise, 0, -∞, or +∞,

depending on whether [=progress value=]

is equal to, less than, or greater than

the shared value.

</div>

ISSUE: Do we need a ''percent-progress()'' notation,

or do enough places auto-convert that it's not necessary?

ISSUE(11825): Should progress() functions clamp to 0-100%?

Note: The ''progress()'' function is essentially syntactic sugar

for a particular pattern of ''calc()'' notations.

<!-- Big Text: *-mix()

█ █ ████ █ █ ██ ██

█ █ ██ ██ ▐▌ █ █ █▌ ▐█

█ █ █▌█ █▐█ ▐▌ █ █ █▌ ▐█

███████ ████▌ █▌ █ ▐█ ▐▌ █ █▌ ▐█

█ █ █▌ ▐█ ▐▌ █ █ █▌ ▐█

█ █ █▌ ▐█ ▐▌ █ █ █▌ ▐█

█▌ ▐█ ████ █ █ ██ ██

-->

<h2 id="mixing">

Weighted Average Notations: the *-mix() family</h2>

Several <dfn export>mix notations</dfn> in CSS

allow representing the weighted average of a set of values.

These [=functional notations=] follow the syntactic pattern:

<pre class=prod>

<var>*mix</var>() = <var>*mix</var>( <var>options</var>? , [ <var>value</var> && <<percentage>>? ]# )

</pre>

where the <var>options</var> can provide type-specific mixing options,

and each <var>value</var> and optional <<percentage>> pair in the argument list

is a <dfn export>mix item</dfn> representing

an input to the mix and its weight in the average.

The [=mix notations=] in CSS include:

* ''calc-mix()'',

for mixing <<number>>, <<length>>, <<percentage>>, <<time>>,

and other dimensions representable in ''calc()'' expressions

* ''transform-mix()'',

for mixing <<transform-list>>s

* ''color-mix()'',

for mixing <<color>> values (see [[css-color-5]])

* ''cross-fade()'',

for mixing <<image>> values (see [[css-images-4]])

* ''palette-mix()'',

for mixing 'font-palette' values (see [[css-fonts-4]])

<h3 id="mix-percentage-normalization">

Normalizing Mix Percentages</h3>

If the sum of the mix percentages are greater than 100%,

they are scaled down;

if it is less, any remaining percentage is distributed to values whose <<percentage>> is omitted,

or else assigned to a “none” type value as defined by the specific [=mix notation=].

<div algorithm>

To <dfn export>normalize mix percentages</dfn>

given

* a [=/list=] of [=mix items=] |items|

(a value and optional percentage, each between 0% and 100% if specified)

* an optional |force normalization| flag

(defaulting to false),

returning a list of [=mix items=] with normalized percentages

and a “leftover” percentage:

1. Let |specified sum| be the sum of the percentages specified in |items|

(clamped to 100%),

or 0% if the percentages are omitted for all items.

2. For each omitted percentage in |items|,

set it to

<code>(100% - |specified sum|) / (number of omitted percentages)</code>.

3. Let |total| be the sum of the percentages of all the items.

4. If |total| is greater than 100%,

or if |total| is greater than 0% and the |force normalization| flag is true,

multiply every percentage in |items| by <code>(100% / |total|)</code>.

5. If |total| is less than 100%,

let |leftover| be <code>(100% - |total|)</code>.

Otherwise, let |leftover| be 0%.

6. Return |items| and |leftover|.

Note: At the end of this algorithm, every percentage is set,

and the sum of all percentages is either 0%

(if they were all specified as 0% to begin with)

or 100%.

The |leftover| value will be applied to the usage-specific “none” type value