CSS Values and Units Module Level 3

1.
Introduction
The value definition field of each CSS property can contain keywords,
data types (which appear between
and
),
and information on how they can be combined.
Generic data types (

being the most widely used)
that can be used by many properties are described in this specification,
while more specific data types (e.g.,

are described in the corresponding modules.
1.1.
Module Interactions
This module replaces and extends the data type definitions in
[CSS2]
sections
1.4.2.1
4.3
and
A.2
2.
Value Definition Syntax
The
value definition syntax
described here
is used to define the set of valid values for CSS properties
(and the valid syntax of many other parts of CSS).
A value so described can have one or more components.
2.1.
Component Value Types
Component value types are designated in several ways:
Keyword
values (such as
auto
disc
, etc.),
which appear literally, without quotes (e.g.
auto
).
Basic data types,
which appear between
and
(e.g.,


, etc.).
For
numeric data types
this type notation can annotate any range restrictions
using the
bracketed range notation
described below.
Property value ranges,
which represent the same pattern of values as a property bearing the same name.
These are written as the property name,
surrounded by single quotes,
between
and
e.g.,
<'border-width'>
<'background-attachment'>
, etc.
These types
do not
include
CSS-wide keywords
such as
inherit
Additionally,
if the property’s value grammar
is a
comma-separated repetition
the corresponding type
does not include the top-level
comma-separated list multiplier
(E.g. if a property named
pairing
is defined as


? ]#
then
<'pairing'>
is equivalent to


? ]
not


? ]#
.)\
Why remove the multiplier?
The top-level multiplier is ripped out of these value types
because top-level comma-separated repetitions are mostly used for
coordinating list properties
and when a shorthand combines several such properties,
it needs the unmultiplied grammar
so it can construct its
own
comma-separated repetition.
Without this special treatment,
every such longhand would have to be defined
with an ad-hoc production just for the inner value,
which makes the grammars harder to understand overall.
Functional notations and their arguments.
These are written as the function’s name,
followed by an empty parentheses pair,
between
and
e.g.

and references the correspondingly-named
functional notation
Other non-terminals.
These are written as the name of the non-terminal
between
and
as in

Notice the distinction between

and
<'border-width'>
the latter represents the grammar of the
border-width
property,
the former requires an explicit expansion elsewhere.
The definition of a non-terminal is typically located near its first appearance in the specification.
Some property value definitions also include the slash (/),
the comma (,),
and/or parentheses as literals.
These represent their corresponding tokens.
Other non-keyword literal characters that may appear in a component value,
such as “+”,
must be written enclosed in single quotes.
Commas
specified in the grammar are implicitly omissible
in some circumstances,
when used to separate optional terms in the grammar.
Within a top-level list in a property or other CSS value,
or a function’s argument list,
a comma specified in the grammar must be omitted if:
all items preceding the comma have been omitted
all items following the comma have been omitted
multiple commas would be adjacent (ignoring
white space
/comments),
due to the items between the commas being omitted.
For example, if a function can accept three arguments in order,
but all of them are optional,
the grammar can be written like:
example
first
second
third
Given this grammar,
writing
example(first, second, third)
is valid,
as is
example(first, second)
or
example(first, third)
or
example(second)
However,
example(first, , third)
is invalid, as one of those commas are no longer separating two options;
similarly,
example(,second)
and
example(first,)
are invalid.
example(first second)
is also invalid,
as commas are still required to actually separate the options.
If commas were not implicitly omittable,
the grammar would have to be much more complicated
to properly express the ways that the arguments can be omitted,
greatly obscuring the simplicity of the feature.
All CSS properties also accept the
CSS-wide keyword values
as the sole component of their property value.
For readability these are not listed explicitly in the property value syntax definitions.
For example, the full value definition of
border-color
under
CSS Cascading and Inheritance Level 3
is

| inherit | initial | unset
(even though it is listed as

).
Note:
This implies that, in general,
combining these keywords with other component values in the same declaration
results in an invalid declaration.
For example,
background: url(corner.png) no-repeat, inherit;
is invalid.
2.2.
Component Value Combinators
Component values can be arranged into property values as follows:
Juxtaposing components means that
all of them must occur, in the given order.
A double ampersand (
&&
) separates two or more components,
all of which must occur, in any order.
A double bar (
||
) separates two or more options:
one or more of them must occur, in any order.
A bar (
) separates two or more alternatives:
exactly one of them must occur.
Brackets ([ ]) are for grouping.
Juxtaposition is stronger than the double ampersand, the double
ampersand is stronger than the double bar, and the double bar
is stronger than the bar. Thus, the following lines are equivalent:
a b | c || d && e f
a b
c ||
d &&
e f
]]]
For reorderable combinators (||, &&),
ordering of the grammar does not matter:
components in the same grouping may be interleaved in any order.
Thus, the following lines are equivalent:
a || b || c
b || a || c
Note:
Combinators are
not
associative, so grouping is significant.
For example,
a || b || c
and
a || [ b || c ]
are distinct grammars:
the first allows a value like
b a c
, but the second does not.
2.3.
Component Value Multipliers
Every type, keyword, or bracketed group may be followed by one of
the following modifiers:
An asterisk (
indicates that the preceding type, word, or group
occurs zero or more times.
A plus (
indicates that the preceding type, word, or group
occurs one or more times.
A question mark (
indicates that the preceding type, word, or group
is optional (occurs zero or one times).
A single number in curly braces (
indicates that the preceding type, word, or group
occurs
times.
A comma-separated pair of numbers in curly braces (
indicates that the preceding type, word, or group
occurs at least
and at most
times.
The
may be omitted ({
,})
to indicate that there must be at least
repetitions,
with no upper bound on the number of repetitions.
A hash mark (
indicates that the preceding type, word, or group
occurs one or more times, separated by comma tokens
(which may optionally be surrounded by
white space
and/or comments).
It may optionally be followed by the curly brace forms, above,
to indicate precisely how many times the repetition occurs,
like
#{1,4}
An exclamation point (
) after a group
indicates that the group is required
and must produce at least one value;
even if the grammar of the items within the group
would otherwise allow the entire contents to be omitted,
at least one component value must not be omitted.
The
and
multipliers may be stacked as
+#
similarly, the
and
multipliers may be stacked as
#?
These stacks each represent the later multiplier
applied to the result of the earlier multiplier.
(These same stacks can be represented using grouping,
but in complex grammars this can push the number of brackets beyond readability.)
For repeated component values (indicated by
, or
),
UAs
must support at least 20 repetitions of the component.
If a property value contains more than the supported number of repetitions,
the declaration must be ignored as if it were invalid.
2.4.
Combinator and Multiplier Patterns
There are a small set of common ways to combine multiple independent
component values
in particular numbers and orders.
In particular, it’s common to want to express that,
from a set of component value,
the author must select zero or more, one or more, or all of them,
and in either the order specified in the grammar or in any order.
All of these can be easily expressed using simple patterns of
combinators
and
multipliers
in order
any order
zero or more
A? B? C?
A? || B? || C?
one or more
A? B? C?
A || B || C
all
A B C
A && B && C
Note that all of the "any order" possibilities are expressed using combinators,
while the "in order" possibilities are all variants on juxtaposition.
2.5.
Component Values and White Space
Unless otherwise specified,
white space
and/or comments may appear before, after, and/or between
components combined using the above
combinators
and
multipliers
Note:
In many cases, spaces will in fact be
required
between components
in order to distinguish them from each other.
For example, the value
1em2em
would be parsed as a single

with the number
and the identifier
em2em
which is an invalid unit.
In this case, a space would be required before the
to get this parsed as the two lengths
1em
and
2em
2.6.
Property Value Examples
Below are some examples of properties with their corresponding value
definition fields
Property
Value definition field
Example value
orphans

text-align
left | right | center | justify
center
padding-top
|
5%
outline-color
| invert
#fefefe
text-decoration
none | underline || overline || line-through || blink
overline underline
font-family
[ | ]#
"Gill Sans", Futura, sans-serif
border-width
[ | thick | medium | thin ]{1,4}
2px medium 4px
box-shadow
[ inset? && {2,4} && ? ]# | none
3px 3px rgba(50%, 50%, 50%, 50%), lemonchiffon 0 0 4px inset
3.
Textual Data Types
The
textual data types
include
various keywords and identifiers
as well as strings (

) and URLs (

).
CSS
identifiers
generically denoted by

consist of a sequence of characters conforming to the

grammar.
[CSS-SYNTAX-3]
Identifiers cannot be quoted;
otherwise they would be interpreted as strings.
CSS properties accept two classes of
identifiers
pre-defined keywords
and
author-defined identifiers
Note:
The

production is not meant for property value definitions—​

should be used instead.
It is provided as a convenience for defining other syntactic constructs.
3.1.
Pre-defined Keywords
In the value definition fields,
keywords
with a pre-defined meaning appear literally.
Keywords are
identifiers
and are interpreted
ASCII case-insensitively
(i.e., [a-z] and [A-Z] are equivalent).
For example, here is the value definition for the
border-collapse
property:
Value
collapse | separate
And here is an example of its use:
table
border-collapse
separate
As defined
above
all properties accept the
CSS-wide keywords
which represent value computations common to all CSS properties.
These keywords are normatively defined in
the
CSS Cascading and Inheritance Module
Tests
Other CSS specifications can define additional CSS-wide keywords.
3.2.
Author-defined Identifiers: the

type
Some properties accept arbitrary author-defined identifiers as a component value.
This generic data type is denoted by

and represents any valid
CSS identifier
that would not be misinterpreted as a pre-defined keyword in that property’s value definition.
Such identifiers are fully case-sensitive,
even in the ASCII range
(e.g.
example
and
EXAMPLE
are two different, unrelated user-defined identifiers).
The
CSS-wide keywords
are not valid

s.
The
default
keyword is reserved
and is also not a valid

Specifications using

must specify clearly
what other keywords are excluded from

, if any—​for example by saying that any pre-defined keywords in that property’s value definition are excluded.
Excluded keywords are excluded in all
ASCII case permutations
When parsing positionally-ambiguous keywords in a property value,

production can only claim the keyword if no other unfulfilled production can claim it.
Note:
When designing grammars with

the

should always be “positionally unambiguous”,
so that it’s impossible to conflict with any keyword values in the property.
3.3.
Quoted Strings: the

type
Strings
are denoted by

When written literally,
they consist of a sequence of characters delimited by double quotes or single quotes,
corresponding to the

production
in the
CSS Syntax Module
[CSS-SYNTAX-3]
Double quotes cannot occur inside double quotes, unless
escaped
(as
"\"
or as
"\22"
).
Analogously for single quotes (
'\'
or
'\27'
).
content
"this is a 'string'."
content
"this is a \"
string\
"."
content
'this is a "string".'
content
'this is a \'
string\
'.'
It is possible to break strings over several lines, for aesthetic or
other reasons, but in such a case the newline itself has to be escaped
with a backslash (\). The newline is subsequently removed from the
string. For instance, the following two selectors are exactly the
same:
Example(s):
title=
"a not s\
o very long title"
/*...*/
title=
"a not so very long title"
/*...*/
Since a string cannot directly represent a newline, to include a
newline in a string, use the escape "\A". (Hexadecimal A is the line
feed character in Unicode (U+000A), but represents the generic notion
of "newline" in CSS.)
3.4.
Resource Locators: the

type
The
url()
functional notation
denoted by

represents a
URL
which is a pointer to a resource.
The typical syntax of a

is:

url


This example shows a URL being used as a background image:
body
background
url
"http://www.example.com/pinkish.gif"
url()
can alternatively be written be written without quotation marks around the URL value,
in which case it is
specially-parsed
as a

; see
CSS Syntax 3
§ 4.3.6 Consume a url token
[CSS-SYNTAX-3]
For example, the following declarations are identical:
background
url
"http://www.example.com/pinkish.gif"
);
background
url
);
Note:
The unquoted
url()
syntax cannot accept a

argument
and has extra escaping requirements:
parentheses,
whitespace
characters,
single quotes (') and double quotes (") appearing in a URL
must be escaped with a backslash,
e.g.
url(open\(parens)
url(close\)parens)
(In quoted

url()
s,
only newlines and the character used to quote the string need to be escaped.)
Depending on the type of URL,
it might also be possible to write these characters as URL-escapes
(e.g.
url(open%28parens)
or
url(close%29parens)
as described in
[URL]
Some CSS contexts (such as
@import
) also allow a

to be represented by a bare

, without the function wrapper.
In such cases the string behaves identically to a
url()
function containing that string.
For example, the following statements act identically:
@import
url
"base-theme.css"
);
@import
"base-theme.css"
3.4.1.
Relative URLs
In order to create modular style sheets that are not dependent on
the absolute location of a resource, authors should use relative URLs.
Relative URLs (as defined in
[URL]
) are resolved to full URLs
using a base URL. RFC 3986, section 3, defines the normative
algorithm for this process.
For CSS style sheets, the base URL is that of the style sheet itself,
not that of the styled source document.
Style sheets embedded within a document have
the base URL associated with their container.
Note:
For HTML documents,
the
base URL is mutable
When a

appears in the computed value of a property,
it is resolved to an absolute URL,
as described in the preceding paragraph.
The computed value of a URL that the
UA
cannot resolve to an absolute URL is the specified value.
For example, suppose the following rule:
body
background
url
"tile.png"
is located in a style sheet designated by the URL:
http
//www.example.org/style/basic.css
The background of the source document’s

will be tiled with whatever image is described by the resource designated by the URL:
http
//www.example.org/style/tile.png
The same image will be used regardless of the URL of the source document containing the

3.4.1.1.
Fragment URLs
To work around some common eccentricities in browser URL handling,
CSS has special behavior for fragment-only urls.
If a
url()
’s value starts with a U+0023 NUMBER SIGN (
) character,
parse it as per normal for URLs,
but additionally set the
local url flag
of the
url()
When matching a
url()
with the
local url flag
set,
ignore everything but the URL’s fragment,
and resolve that fragment against the current document that relative URLs are resolved against.
This reference must always be treated as same-document
(rather than cross-document).
When
serializing
url()
with the
local url flag
set,
it must serialize as just the fragment.
What “browser eccentricities”?
Theoretically, browsers should re-resolve any relative URLs,
including fragment-only URLs,
whenever the document’s base URL changes
(such as through mutation of the
base
element,
or calling
pushState()
).
In many cases they don’t, however,
and so without special handling,
fragment-only URLs will suddenly become cross-document references
(pointing at the previous base URL)
and break in many of the places they’re used.
Since fragment-only URLs express a clear semantic
of wanting to refer to the current document
regardless of what its current URL is,
this hack preserves the expected behavior at least in these cases.
3.4.2.
Empty URLs
If the value of the

is the empty string
(like
url("")
or
url()
),
the url must resolve to an invalid resource
(similar to what the url
about:invalid
does).
Its computed value is
url("")
and it must serialize as such.
Tests
Note:
This matches the behavior of empty urls for embedded resources elsewhere in the web platform,
and avoids excess traffic re-requesting the stylesheet or host document
due to editing mistakes leaving the
url()
value empty,
which are almost certain to be invalid resources for whatever the
url()
shows up in.
Linking on the web platform
does
allow empty urls,
so if/when CSS gains some functionality to control hyperlinks,
this restriction can be relaxed in those contexts.
3.4.3.
URL Modifiers
The
url()
function supports specifying additional

s,
which change the meaning or the interpretation of the URL somehow.

is either an

or a
functional notation
This specification does not define any

s,
but other specs may do so.
Note:

that is either unquoted or not wrapped in
url()
notation
cannot accept any

s.
4.
Numeric Data Types
Numeric data types are used to represent
quantities, indexes, positions, and other such values.
Although many syntactic variations can exist
in expressing the quantity (numeric aspect) in a given numeric value,
the
specified
and
computed value
do not distinguish these variations:
they represent the value’s abstract quantity,
not its syntactic representation.
The
numeric data types
include



and various
dimensions
including




, and

Note:
While general-purpose
dimensions
are defined here,
some other modules define additional data types
(e.g.
[css-grid-1]
introduces
fr
units)
whose usage is more localized.
4.1.
Range Restrictions and Range Definition Notation
Properties can restrict numeric values to some range.
If the value is outside the allowed range,
then unless otherwise specified,
the declaration is invalid and must be
ignored
Range restrictions can be annotated in the numeric type notation
using
CSS bracketed range notation
—​
min
max
—​within the angle brackets, after the identifying keyword,
indicating a closed range
between (and including)
min
and
max
For example,

indicates an integer between
and
10
, inclusive,
while

indicates an angle between
0deg
and
180deg
(expressed in any unit).
Note:
CSS values generally do not allow open ranges;
thus only square-bracket notation is used.
CSS theoretically supports infinite precision and infinite ranges for all value types;
however in reality implementations have finite capacity.
UAs
should support reasonably useful ranges and precisions.
Range extremes that are ideally unlimited
are indicated using ∞ or −∞ as appropriate.
For example,

indicates a non-negative length.
If no range is indicated,
either by using the
bracketed range notation
or in the property description,
then
−∞
is assumed.
Values of −∞ or ∞ must be written without units,
even if the value type uses units.
Values of
can
be written without units,
even if the value type doesn’t allow “unitless zeroes”
(such as

).
Note:
At the time of writing,
the
bracketed range notation
is new;
thus in most CSS specifications
any range limitations are described only in prose.
(For example, “Negative values are not allowed” or
“Negative values are invalid”
indicate a
range.)
This does not make them any less binding.
4.2.
Integers: the

type
Integer values are denoted by

When written literally,
an
integer
is one or more decimal digits
through
and corresponds to a subset of the

production
in the CSS Syntax Module
[CSS-SYNTAX-3]
The first digit of an integer may be immediately preceded by
or
to indicate the integer’s sign.
Tests
4.3.
Real Numbers: the

type
Number values are denoted by

and represent real numbers, possibly with a fractional component.
Tests
When written literally,
number
is either an
integer
or zero or more decimal digits followed by a dot (.) followed by one or more decimal digits;
optionally, it can be concluded by the letter “e” or “E”
followed by an integer indicating the base-ten exponent
in
scientific notation
It corresponds to the

production
in the
CSS Syntax Module
[CSS-SYNTAX-3]
As with integers, the first character of a number
may be immediately preceded by
or
to indicate the number’s sign.
4.4.
Numbers with Units:
dimension
values
The general term
dimension
refers to
a number with a unit attached to it;
and is denoted by

When written literally,
dimension
is a
number
immediately followed by a unit identifier,
which is an
identifier
It corresponds to the

production
in the
CSS Syntax Module
[CSS-SYNTAX-3]
Like keywords, unit identifiers are
ASCII case-insensitive
Tests
CSS uses

s to specify
distances (

),
durations (

),
frequencies (

),
resolutions (

),
and other quantities.
4.4.1.
Compatible Units
When
serializing
computed values
[CSSOM]
compatible units
(those related by a static multiplicative factor,
like the 96:1 factor between
px
and
in
or the computed
font-size
factor between
em
and
px
are converted into a single
canonical unit
Each group of compatible units defines which among them is the
canonical unit
that will be used for serialization.
When serializing
resolved values
that are
used values
all value types (percentages, numbers, keywords, etc.)
that represent lengths are considered
compatible
with lengths.
Likewise any future API that returns
used values
must consider any values that represent distances/durations/frequencies/etc.
as
compatible
with the relevant class of
dimensions
and canonicalize accordingly.
Tests
4.5.
Percentages: the

type
Percentage values are denoted by

and indicates a value that is some fraction of another reference value.
When written literally,
percentage
consists of a
number
immediately followed by a percent sign
It corresponds to the

production
in the
CSS Syntax Module
[CSS-SYNTAX-3]
Percentage values are always relative to another quantity,
for example a length.
Each property that allows percentages also defines the quantity to which the percentage refers.
This quantity can be a value of another property for the same element,
the value of a property for an ancestor element,
a measurement of the formatting context
(e.g., the width of a
containing block
),
or something else.
Tests
4.6.
Mixing Percentages and Dimensions
In cases where a

can represent the same quantity
as a
dimension
in the same
component value
position,
and can therefore be combined with them in a
calc()
expression,
the following convenience notations may be used in the property grammar:

Equivalent to


where the

will resolve to a


Equivalent to


where the

will resolve to a


Equivalent to


where the

will resolve to an


Equivalent to


where the

will resolve to a

For example, the
width
property can accept a

or a

both representing a measure of distance.
This means that
width: calc(500px + 50%);
is allowed—​both values are converted to absolute lengths and added.
If the containing block is
1000px
wide,
then
width: 50%;
is equivalent to
width: 500px
and
width: calc(50% + 500px)
thus ends up equivalent to
width: calc(500px + 500px)
or
width: 1000px
On the other hand, the second and third arguments of the
hsl()
function
can only be expressed as

s.
Although
calc()
productions are allowed in their place,
they can only combine percentages with themselves,
as in
calc(10% + 20%)
Note:
Specifications should never alternate

in place of a dimension
in a grammar unless they are
compatible
Note:
More <
type
-percentage> productions can be added in the future as needed.
A will never be added,
as

and

can’t be combined in
calc()
5.
Distance Units: the

type
Lengths refer to distance measurements
and are denoted by

in the property definitions.
A length is a
dimension
For zero lengths the unit identifier is optional
(i.e. can be syntactically represented as the

).
However, if a
could be parsed as either a

or a

in a property
(such as
line-height
),
it must parse as a

Properties may restrict the length value to some range.
If the value is outside the allowed range,
the declaration is invalid and must be
ignored
Tests
While some properties allow negative length values,
this may complicate the formatting and there may be implementation-specific limits.
If a negative length value is allowed but cannot be supported,
it must be converted to the nearest value that can be supported.
In cases where the
used
length cannot be supported,
user agents must approximate it in the
actual
value.
There are two types of length units:
relative
and
absolute
Tests
5.1.
Relative Lengths
Relative length units
specify a length relative to another length.
Style sheets that use relative units can more easily scale from one output environment to another.
The relative units are:
Informative Summary of Relative Units
unit
relative to
em
font size of the element
ex
x-height of the element’s font
ch
character advance
of the “0” (ZERO, U+0030) glyph in the element’s font
rem
font size of the root element
vw
1% of viewport’s width
vh
1% of viewport’s height
vmin
1% of viewport’s smaller dimension
vmax
1% of viewport’s larger dimension
Child elements do not inherit the relative values as specified for their parent;
they inherit the
computed values
5.1.1.
Font-relative Lengths: the
em
ex
ch
rem
units
The
font-relative lengths
refer to the font metrics of the element on which they are used—​or, in the case of
rem
, the metrics of the root element.
em
Equal to the computed value of the
font-size
property of the element on which it is used.
The rule:
h1
line-height
1.2
em
means that the line height of
h1
elements
will be 20% greater than the font size of
h1
element.
On the other hand:
h1
font-size
1.2
em
means that the font size of
h1
elements
will be 20% greater than the computed font size inherited by
h1
elements.
rem
Equal to the computed value of the
em
unit on the root element.
Tests
ex unit
Equal to the used x-height of the
first available font
[CSS3-FONTS]
The x-height is so called because it is often equal to the height of the lowercase "x".
However, an
ex
is defined even for fonts that do not contain an "x".
The x-height of a font can be found in different ways.
Some fonts contain reliable metrics for the x-height.
If reliable font metrics are not available,
UAs
may determine the x-height from the height of a lowercase glyph.
One possible heuristic is to look at
how far the glyph for the lowercase "o" extends below the baseline,
and subtract that value from the top of its bounding box.
In the cases where it is impossible or impractical to determine the x-height,
a value of 0.5em must be assumed.
Tests
ch unit
Represents the typical
advance measure
of European alphanumeric characters,
and measured as the used
advance measure
of the “0” (ZERO, U+0030) glyph
in the font used to render it.
(The
advance measure
of a glyph is its advance width or height,
whichever is in the inline axis of the element.)
Note:
This measurement is an approximation
(and in monospace fonts, an exact measure)
of a single narrow glyph’s
advance measure
thus allowing measurements based on an expected glyph count.
Note:
The advance measure of a glyph depends on writing-mode and text-orientation
as well as font settings, text-transform, and any other properties that affect glyph selection or orientation.
In the cases where it is impossible or impractical to determine the measure of the “0” glyph,
it must be assumed to be 0.5em wide by 1em tall.
Thus, the
ch
unit falls back to
0.5em
in the general case,
and to
1em
when it would be typeset upright
(i.e.
writing-mode
is
vertical-rl
or
vertical-lr
and
text-orientation
is
upright
).
Tests
When used outside the context of an element
(such as in
media queries
),
these units refer to the computed font metrics corresponding to the initial values of the
font
property.
When used in the value of the
font-size
property on the element they refer to,
these units refer to the computed font metrics of the parent element
(or the computed font metrics corresponding to the initial values of the
font
property,
if the element has no parent).
The
font-relative lengths
are calculated in the absence of shaping.
5.1.2.
Viewport-percentage Lengths: the
vw
vh
vmin
vmax
units
The
viewport-percentage lengths
are relative to the size of the
initial containing block
—​which is itself based on the size of either
the viewport (for
continuous media
or the
page area
(for
paged media
).
When the height or width of the initial containing block is changed,
they are scaled accordingly.
However, any scrollbars are assumed not to exist.
For
paged media
, the exact definition of the viewport-percentage lengths
is deferred to
[CSS3PAGE]
vw unit
Equal to 1% of the width of the initial containing block.
In the example below, if the width of the viewport is 200mm,
the font size of
h1
elements will be 16mm
(i.e. (8×200mm)/100).
h1
font-size
vw
vh unit
Equal to 1% of the height of the initial containing block.
vmin unit
Equal to the smaller of
vw
or
vh
vmax unit
Equal to the larger of
vw
or
vh
Tests
5.2.
Absolute Lengths: the
cm
mm
in
pt
pc
px
units
The
absolute length units
are fixed in relation to each other
and
anchored
to some physical measurement.
They are mainly useful when the output environment is known.
The absolute units consist of
the
physical units
in
cm
mm
pt
pc
and the
visual angle unit (pixel unit)
px
):
unit
name
equivalence
cm
centimeters
1cm = 96px/2.54
mm
millimeters
1mm = 1/10th of 1cm
quarter-millimeters
1Q = 1/40th of 1cm
in
inches
1in = 2.54cm = 96px
pc
picas
1pc = 1/6th of 1in
pt
points
1pt = 1/72nd of 1in
px
pixels
1px = 1/96th of 1in
h1
margin
0.5
in
/* inches */
h2
line-height
cm
/* centimeters */
h3
word-spacing
mm
/* millimeters */
h3
letter-spacing
/* quarter-millimeters */
h4
font-size
12
pt
/* points */
h4
font-size
pc
/* picas */
font-size
12
px
/* px */
Note:
Lengths in publishing contexts
are sometimes written like
indicating a length of 2 picas and 3 points.
These can be written in CSS as
calc(2pc + 3pt)
(see
§ 8.1 Mathematical Expressions: calc()
).
All of the absolute length units are
compatible
and
px
is their
canonical unit
For a CSS device, these dimensions are
anchored
either
by relating the
physical units
to their physical measurements, or
by relating the
pixel unit
to the
reference pixel
For print media at typical viewing distances,
the
anchor unit
should be one of the
physical units
(inches, centimeters, etc).
For screen media (including high-resolution devices),
low-resolution devices,
and devices with unusual viewing distances,
it is recommended instead that the
anchor unit
be the
pixel unit
For such devices it is recommended that the
pixel unit
refer to the whole number of
device pixels
that best approximates the reference pixel.
Note:
If the
anchor unit
is the
pixel unit
the
physical units
might not match their physical measurements.
Alternatively if the
anchor unit
is a
physical unit
the
pixel unit
might not map to a whole number of
device pixels
Note:
This definition of the
pixel unit
and the
physical units
differs from the earlier editions of CSS1 and CSS2.
In particular, in previous versions of CSS the
pixel unit
and the
physical units
were not related by a fixed ratio:
the
physical units
were always tied to their physical measurements
while the
pixel unit
would vary to most closely match the reference pixel.
(This unfortunate change
was made because too much existing content relies on the assumption of 96dpi,
and breaking that assumption broke the content.)
Note:
Units are
ASCII case-insensitive
and serialize as lowercase, for example 1Q serializes as 1q.
Tests
The
reference pixel
is the visual angle of one pixel on a device with a
device pixel
density of 96dpi
and a distance from the reader of an arm’s length.
For a nominal arm’s length of 28 inches,
the visual angle is therefore about 0.0213 degrees.
For reading at arm’s length,
1px thus corresponds to about 0.26 mm (1/96 inch).
The image below illustrates the effect of viewing distance on the size of a reference pixel:
a reading distance of 71 cm (28 inches)
results in a reference pixel of 0.26 mm,
while a reading distance of 3.5 m (12 feet)
results in a reference pixel of 1.3 mm.
Showing that pixels must become larger if the viewing distance increases
This second image illustrates the effect of a device’s resolution on the pixel unit:
an area of 1px by 1px is covered by a single dot in a low-resolution device
(e.g. a typical computer display),
while the same area is covered by 16 dots in a higher resolution device
(such as a printer).
Showing that more device pixels (dots) are needed
to cover a 1px by 1px area on a high-resolution device
than on a lower-resolution one
(of the same approximate viewing distance)
Tests
device pixel
is the smallest unit of area on the device output
capable of displaying its full range of colors.
For typical color screens, it’s a square or somewhat rectangular region
containing a red, green, and blue subpixel.
Many non-traditional outputs exist that can blur this definition,
such as by displaying some colors at higher resolutions.
Such devices still expose some equivalent notion of "device pixel",
however.
6.
Other Quantities
6.1.
Angle Units: the

type and
deg
grad
rad
turn
units
Angle values are

s denoted by

The angle unit identifiers are:
deg
Degrees. There are 360 degrees in a full circle.
grad
Gradians, also known as "gons" or "grades".
There are 400 gradians in a full circle.
rad
Radians. There are 2π radians in a full circle.
turn
Turns. There is 1 turn in a full circle.
For example, a right angle is
90deg
or
100grad
or
0.25turn
or
approximately
1.57rad
All

units are
compatible
and
deg
is their
canonical unit
By convention,
when an angle denotes a direction in CSS,
it is typically interpreted as a
bearing angle
where 0deg is "up" or "north" on the screen,
and larger angles are more clockwise
(so 90deg is "right" or "east").
For example, in the
linear-gradient()
function,
the

that determines the direction of the gradient
is interpreted as a bearing angle.
Note:
For legacy reasons,
some uses of

allow a bare
to mean
0deg
This is not true in general, however,
and will not occur in future uses of the

type.
Tests
6.2.
Duration Units: the

type and
ms
units
Time values are
dimensions
denoted by

The time unit identifiers are:
Seconds.
ms
Milliseconds. There are 1000 milliseconds in a second.
All

units are
compatible
and
is their
canonical unit
Properties may restrict the time value to some range.
If the value is outside the allowed range,
the declaration is invalid and must be
ignored
Tests
6.3.
Frequency Units: the

type and
Hz
kHz
units
Frequency values are
dimensions
denoted by

The frequency unit identifiers are:
Hz
Hertz. It represents the number of occurrences per second.
kHz
KiloHertz. A kiloHertz is 1000 Hertz.
For example, when representing sound pitches, 200Hz (or 200hz)
is a bass sound, and 6kHz (or 6khz) is a treble sound.
All

units are
compatible
and
hz
is their
canonical unit
Note:
Units are
ASCII case-insensitive
and serialize as lowercase, for example 1Hz serializes as 1hz.
6.4.
Resolution Units: the

type and
dpi
dpcm
dppx
units
Resolution units are
dimensions
denoted by

The resolution unit identifiers are:
dpi
Dots per inch.
dpcm
Dots per centimeter.
dppx
Dots per
px
unit.
The

unit represents the size of a single "dot" in a graphical representation
by indicating how many of these dots fit in a CSS
in
cm
, or
px
For uses, see e.g. the
resolution
media query in
[MEDIAQ]
or the
image-resolution
property defined in
[CSS3-IMAGES]
All

units are
compatible
and
dppx
is their
canonical unit
The allowed range of

values
always
excludes negative values,
in addition to any explicit ranges that might be specified.
Note that due to the 1:96 fixed ratio of CSS
in
to CSS
px
1dppx
is equivalent to
96dpi
This corresponds to the default resolution of images displayed in CSS:
see
image-resolution
The following @media rule uses Media Queries
[MEDIAQ]
to assign some special style rules to devices that use two or more device pixels per CSS
px
unit:
@media
min-resolution:
dppx
...
7.
Data Types Defined Elsewhere
Some data types are defined in their own modules.
This example talks about some of the most common ones
used across several specifications.
7.1.
Colors: the

type
The

data type is defined in
[CSS3COLOR]
UAs that support CSS Color Level 3 or its successor must interpret

as defined therein.
7.2.
Images: the

type
The

data type is defined in
[CSS3-IMAGES]
UAs that support CSS Images Level 3 or its successor
must interpret

as defined therein.
UAs that do not yet support CSS Images Level 3
must interpret

as

7.3.
2D Positioning: the

type
The

value specifies the position of a object area (e.g. background image)
inside a positioning area (e.g. background positioning area).
It is computed and interpreted as specified for
background-position
[CSS3-BACKGROUND]

left
center
right
top
bottom

left
center
right
&&
top
center
bottom
left
center
right

top
center
bottom

left
right

&&
top
bottom

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.
The canonical order when serializing is
the horizontal component followed by the vertical component.
When specified in a grammar alongside other keywords,

s, or

s,

is
greedily
parsed;
it consumes as many components as possible.
For example,
transform-origin
defines a 3D position
as (effectively)


A value such as
left 50px
will be parsed as a 2-value

with an omitted z-component;
on the other hand,
a value such as
top 50px
will be parsed as a single-value

followed by a

8.
Functional Notations
functional notation
is a type of component value
that can represent more complex types or invoke special processing.
The syntax starts with the name of the function
immediately followed by a left parenthesis
(i.e. a

followed by the argument(s) to the notation
followed by a right parenthesis.
Like keywords, function names are
ASCII case-insensitive
White space
is allowed, but optional,
immediately inside the parentheses.
Functions can take multiple arguments,
which are formatted similarly to a CSS property value.
Note:
Some legacy
functional notations
, such as
rgba()
, use commas unnecessarily,
but generally commas are only used to separate items in a list,
or pieces of a grammar that would be ambiguous otherwise.
If a comma is used to separate arguments,
white space
is optional before and after the comma.
background
url
);
color
rgb
100
200
50
);
content
counter
list-item
". "
width
calc
50
em
);
8.1.
Mathematical Expressions:
calc()
The
calc()
function
allows a numeric CSS component value
to be written as a mathematical expression
using addition (
), subtraction (
), multiplication (
), and/or division (
).
The
calc()
expression represents the result of the mathematical calculation it contains,
which is evaluated using standard operator precedence rules
and
bind tighter than
and
and operators are otherwise evaluated left-to-right).
It can be used wherever






, or

values are allowed.
Components of a
calc()
expression can be literal values or
or
calc()
expressions.
section
float
left
margin
em
border
solid
px
width
calc
100
em
px
);
margin
calc
rem
px
calc
rem
px
);
The following sets the
font-size
so that exactly 40em fits within the viewport,
ensuring that roughly the same amount of text always fills the screen no matter the screen size.
:root
font-size
calc
100
vw
40
);
If the rest of the design is specified using the
rem
unit,
the entire layout will scale to match the viewport width.
The following example stacks two background images,
with the first perfectly centered
and the second offset 20px to the bottom and to the left of the first.
.foo
background
url
top.png
),
url
bottom.png
);
background-repeat
no-repeat
background-position
50
50
calc
50
20
px
calc
50
20
px
);
This example shows how to place color-stops on a gradient an equal distance from either end.
.foo
background-image
linear-gradient
to right
silver
white
50
px
white
calc
100
50
px
),
silver
);
Tests
8.1.1.
Syntax
The syntax of a
calc()
function is:
calc
()
calc



'+'
'-'



'*'









'+'
'-'



'*'





In addition,
white space
is required on both sides of the
and
operators.
(The
and
operators can be used without white space around them.)
UAs must support
calc()
expressions of at least 20 terms,
where each
NUMBER
DIMENSION
, or
PERCENTAGE
is a term.
If a
calc()
expression contains more than the supported number of terms,
it must be treated as if it were invalid.
8.1.2.
Type Checking
A math expression has a
resolved type
, which is one of






, or

The
resolved type
must be valid for where the expression is placed;
otherwise, the expression is invalid.
The
resolved type
of the expression is determined by the types of the values it contains.

s are of type

or


’s type is given by its unit
cm
is

deg
is

, etc.).
Note:
Because

s are always interpreted as

s or

s,
"unitless 0"

s aren’t supported in
calc()
That is,
width: calc(0 + 5px);
is invalid,
even though both
width: 0;
and
width: 5px;
are valid.
If percentages are accepted in the context in which the expression is placed,
and they are defined to be relative to another type besides


is treated as that type.
For example, in the
width
property, percentages have the

type.
A percentage only has the

type if in that context

values are not used-value compatible with any other type.
If percentages are not normally allowed in place of the
calc()
then a
calc()
expression containing percentages is invalid in that context.
Note:
Note that

s relative to

s,
such as in
opacity
are not allowed in
calc()
Allowing this would cause significant problems with "unit algebra"
(allowing multiplication/division of

s),
and in every case so far,
doesn’t provide any new functionality.
(For example,
opacity: 25%
is identical to
opacity: .25
it’s just a trivial syntax transform.)
Note:
Although there are a few properties in which a bare

becomes a

at used-value time
(specifically,
line-height
and
tab-size
),

s never become "length-like" in
calc()
They always stay as

s.
Operators form sub-expressions, which gain types based on their arguments.
To make expressions simpler,
operators have restrictions on the types they accept.
At each operator,
the types of the left and right argument are checked for these restrictions.
If compatible, the type resolves as described below
(the following ignores precedence rules on the operators for simplicity):
At
or
check that both sides have the same type,
or that one side is a

and the other is an

If both sides are the same type,
resolve to that type.
If one side is a

and the other is an

resolve to

At
check that at least one side is

If both sides are

resolve to

Otherwise,
resolve to the type of the other side.
At
check that the right side is

If the left side is

resolve to

Otherwise,
resolve to the type of the left side.
If an operator does not pass the above checks, the expression is invalid.
Also, division by zero is invalid. This includes both dividing by the
literal number zero, as well as any numeric expression that evaluates to zero
(as purely-numeric expressions can be evaluated without any additional
information at parse time).
Note:
Algebraic simplifications do not affect the validity of the
calc()
expression or its resolved type.
For example,
calc(5px - 5px + 10s)
and
calc(0 * 5px + 10s)
are both invalid
due to the attempt to add a length and a time.
Tests
8.1.3.
Computed Value
The computed value of a
calc()
expression is the expression
with all components computed.
Where percentages are not resolved at computed-value time,
they are not resolved in
calc()
expressions,
e.g.
calc(100% - 100% + 1em)
resolves to
calc(1em + 0%)
not to
1em
If there are special rules for computing percentages in a value
(e.g.
the
height
property
),
they apply whenever a
calc()
expression contains percentages.
Given the complexities of width and height calculations on table cells and table elements,
math expressions involving percentages for widths and heights on
table columns, table column groups, table rows, table row groups, and table cells
in both auto and fixed layout tables
MAY be treated as if
auto
had been specified.
Tests
8.1.4.
Range Checking
Parse-time range-checking of values is not performed within
calc()
and therefore out-of-range values do not cause the declaration to become invalid.
However, the value resulting from an expression
must be clamped to the range allowed in the target context.
Clamping is performed on
computed values
to the extent possible,
and also on
used values
if computation was unable to sufficiently simplify the expression
to allow range-checking.
(Clamping is not performed on
specified values
.)
Note:
This requires all contexts accepting
calc()
to define their allowable values as a closed (not open) interval.
Since widths smaller than 0px are not allowed,
these three declarations are equivalent:
width
calc
px
10
px
);
width
calc
-5
px
);
width
px
Note however that
width: -5px
is not equivalent to
width: calc(-5px)
Out-of-range values
outside
calc()
are syntactically invalid,
and cause the entire declaration to be dropped.
Tests
8.1.5.
Serialization
The serialization of
calc()
values is undefined in this level.
Appendix A: IANA Considerations
Registration for the
about
invalid
URL scheme
This sections defines and registers the
about
invalid
URL,
in accordance with the registration procedure defined in
[RFC6694]
The official record of this registration can be found at
Registered Token
invalid
Intended Usage
The
about
invalid
URL references a non-existent document with a generic error condition.
It can be used when a URL is necessary, but the default value shouldn’t be resolvable as any type of document.
Contact/Change controller
CSS WG <
www-style@w3.org
> (on behalf of W3C)
Specification
CSS Values and Units Module Level 3
Acknowledgments
Comments and suggestions from
Giovanni Campagna,
Christoph Päper,
Keith Rarick,
Alex Mogilevsky,
Ian Hickson,
David Baron,
Edward Welbourne,
Boris Zbarsky,
Björn Höhrmann
and Michael Day
improved this module.
Changes
Changes since the
1 December 2022 Candidate Recommenation Snapshot
are:
Changes since the
6 June 2019 Candidate Recommendation
are:
Changes since the
31 January 2019 Candidate Recommendation
are:
Changes since the
14 August 2018 Candidate Recommendation
are:
Defined
<'property'>
syntax to refer to the property without any top-level #-multiplier,
to make the notation usable with common list-valued property patterns.
Issue 3146
Clarified that numeric values outside the allowed range
are not ignored if a more specific spec defines other handling.
Issue 3270
Properties may restrict numeric values to some range.
If the value is outside the allowed range,
unless otherwise specified,
the declaration is invalid and must be
ignored
Fixed some
background-position
examples to be less confusing.
Issue 3482
Disposition of Comments
is available.
Changes since the
29 September 2016 Candidate Recommendation
are:
Removed
consideration of scrollbars
in computing viewport units due to lack of implementations.
Issue 15
Inlined the

definition and dropped the three-value syntaxes
to allow for unambiguous combination in complex grammars.
This effectively removes that syntax from
object-position
but allows

to be re-used e.g. in
[CSS-TRANSFORMS-1]
for 3D positions.
(See
discussion
.)
Reverted previous change to allow zero angles to drop their unit;
this will instead be special-cased where needed for backwards-compatibility.
(See
discussion
Defined that range checking, and any resulting clamping, of
calc()
values
is performed both at computed time and at used time.
Issue #434
Fixed grammar error that disallowed numeric expressions as denominators in
calc()
Issue 12
Defined handling of font-relative units outside the context of an element.
Issue 9
Defined that
parses as

if it’s ambiguous whether it’s a

or a

Issue 489
Defined empty
url()
s to refer to an invalid URL, rather than resolving to the URL of the style sheet.
Issue 2211
Removed (unused) ability for percentages to be treated as a

type in
calc()
Issue 1463
Clarified that high-resolution screens should anchor on device pixels, not physical units.
Issue 8
Clarified definition of
url()
to normatively say that it accepts unquoted syntax.
Defined that fragment-only
url()
are specially handled to always be page-local links,
regardless of base-url shenanigans.
(See
§ 3.4.1.1 Fragment URLs
.)
Defined attr() parsing in terms of the Syntax spec, not CSS2.1 grammar.
Disposition of Comments
is available.
Changes since the
11 June 2015 Candidate Recommendation
are:
Dropped
toggle()
for lack of implementations.
Allow zero angles to be represented as
(Change due to Web-compatibility constraints in transform and gradient syntaxes.)
Defined
special handling
for fragment URLs.
Defined an empty

resolves to an invalid resource.
Defined
compatible units
and
canonical units
for serialization.
Defined case-sensitivity of
url()
attribute argument to match attribute selectors.
Added definition of

notation to definition of
identifiers
Added

as a shorthand for


along with equivalent productions for angles, numbers, times, and frequencies.
Allowed

s inside
calc()
to resolve as their own type,
if they occur in some (as yet theoretical) context
where they are not compatible with any other type.
Various clarifications and editorial improvements.
Changes since the
30 July 2013 Candidate Recommendation
are:
Specified that, in the absence of font information,
1ch
equal
.5em
Added
unit.
Relaxed unnecessary restrictions on

Require specs referencing it to be clear about excluded keywords,
because the new rule isn’t as simple.
Clarified relative URL resolution for embedded style sheets.
Clarified {
} variant of {
} notation.
Added notation for restricting the length of comma-separated lists
specified with the
notation.
Clarified handling of
toggle()
when used in shorthand declarations.
Clarified that stringing together reorderable combinations allows interleaving.
Changed syntax references from the 2.1 grammar to the Syntax spec.
Disposition of Comments
is available.
Changes since the
28 August 2012 Candidate Recommendation
are:
Changes since the
4 April 2013 Candidate Recommendation
are:
Noted that the list of
CSS-wide keywords
may be expanded by other specs.
Clarified definition of
ex
to refer to the “first available font”.
Specified that
attr()
with
string
or
url
types doesn’t reparse the attribute contents, just takes the value literally as the value of a

Security Considerations
This specification presents no new security considerations.
This specification defines the
url()
function (

),
which allows CSS to make network requests.
Depending on what features they are used in,
these can potentially expose whether or not the user has access to resources on a network,
and expose information about their contents
(such as the rules within a style sheet, the size of an image, the metrics of a font).
They can also allow exfiltrating data via URL.
Privacy Considerations
This specification introduces units that expose the user’s screen size
(the
viewport-percentage lengths
),
default font size,
and potentially some information about
which fonts are available on the user’s system
(the
font-relative lengths
).
This specification defines the
url()
function (

),
which allows CSS to make network requests.
Depending on what features they are used in,
these can potentially expose whether or not the user has access to resources on a network,
and expose information about their contents
(such as the rules within a style sheet, the size of an image, the metrics of a font).
They can also allow exfiltrating data via URL.
Conformance requirements are expressed with a combination of
descriptive assertions and RFC 2119 terminology. The key words “MUST”,
“MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
“RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this
document are to be interpreted as described in RFC 2119.
However, for readability, these words do not appear in all uppercase
letters in this specification.
All of the text of this specification is normative except sections
explicitly marked as non-normative, examples, and notes.
[RFC2119]
Examples in this specification are introduced with the words “for example”
or are set apart from the normative text with
class=
"example"
like this:
Informative notes begin with the word “Note” and are set apart from the
normative text with
class=
"note"
, like this:
Note, this is an informative note.
Advisements are normative sections styled to evoke special attention and are
set apart from other normative text with
"advisement"
, like
this:
UAs MUST provide an accessible alternative.
Conformance to this specification
is defined for three conformance classes:
A style sheet is conformant to this specification
if all of its statements that use syntax defined in this module are valid
according to the generic CSS grammar and the individual grammars of each
feature defined in this module.
A renderer is conformant to this specification
if, in addition to interpreting the style sheet as defined by the
appropriate specifications, it supports all the features defined
by this specification by parsing them correctly
and rendering the document accordingly. However, the inability of a
UA to correctly render a document due to limitations of the device
does not make the UA non-conformant. (For example, a UA is not
required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification
if it writes style sheets that are syntactically correct according to the
generic CSS grammar and the individual grammars of each feature in
this module, and meet all other conformance requirements of style sheets
as described in this module.
So that authors can exploit the forward-compatible parsing rules to
assign fallback values, CSS renderers
must
treat as invalid (and
ignore
as appropriate
) any at-rules, properties, property values, keywords,
and other syntactic constructs for which they have no usable level of
support. In particular, user agents
must not
selectively
ignore unsupported component values and honor supported values in a single
multi-value property declaration: if any value is considered invalid
(as unsupported values must be), CSS requires that the entire declaration
be ignored.
Once a specification reaches the Candidate Recommendation stage,
non-experimental implementations are possible, and implementors should
release an unprefixed implementation of any CR-level feature they
can demonstrate to be correctly implemented according to spec.
To establish and maintain the interoperability of CSS across
implementations, the CSS Working Group requests that non-experimental
CSS renderers submit an implementation report (and, if necessary, the
testcases used for that implementation report) to the W3C before
releasing an unprefixed implementation of any CSS features. Testcases
submitted to W3C are subject to review and correction by the CSS
Working Group.