MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla

Revision 312021 of Value definition syntax

  • Revision slug: CSS/Value_definition_syntax
  • Revision title: Value definition syntax
  • Revision id: 312021
  • Created:
  • Creator: teoli
  • Is current revision? No
  • Comment

Revision Content

{{ CSSRef() }}

A formal grammar, the CSS value definition syntax, is used for defining the set of valid values that a CSS property or function. In addition to this syntax, the set of valid values can be further restricted by semantic constraints (like, for a number, to be strictly positive).

The definition syntax describes which are allowed and how they interact between them. A component can be a keyword, some characters considered as a litteral, or a value of a given CSS data type or of another CSS property.

Component value types

Keywords

Generic keywords

A keyword with a predefined meaning appears litterally, without quote: e.g. auto, smaller or ease-in.

The specific case of inherit and initial

All CSS properties accept the keywords inherit and initial that are defined CSS-wide. They are not shown in the value definition, and are implicitly defined.

Litterals

In CSS a few characters can appear on their own, like the slash ('/') or the comma (','), and are used in properties to separate part of it. The comma is often used to separate values in enumeration, or parameters in mathematical-like functions, the slash often separate semantically different part of the value but with a common syntax. Typically, the slash is sometimes used in shorthand properties to separate components of the same types but coming from different properties.

Both symbol appear litteraly in a value definition.

Data types

Basic data types

Some kind of data are used throughout CSS and are defined once for all in the specification. Called basic data types, they are represented with their name surrounded by the symbol '<' and '>': {{ xref_cssangle() }}, {{ xref_cssstring() }}, …

Non-terminal data types

Less common data types, called non-terminal data types, are also surrounded  by '<' and '>'.

Non-terminal data types are of two kinds:

  • data types sharing the same name of a property, put between quotes. In this case the data type shares the same set of value than the property. They are often used in the definition of shorthand properties.
  • data type not sharing the same name of a property. These data types are very close to the basic data types. They only differ from the basic data types in the physical location fo their definition: in this case the definition is usually physically very close to the definition of the property using them.

Component value combinators

Juxtaposition

Placing several keywords, litterals, or data types, one next to the other only separated by one or several spaces is called juxtaposition. All juxtaposed components are mandatory and should appear in this very same order.

bold <length> , thin

This example matches the following values:

  • bold 1em, thin
  • bold 0, thin
  • bold 2.5cm, thin
  • bold 3vh, thin

But not:

  • thin 1em, bold as the entities must be in the expressed order
  • bold 1em thin as the entities are mandatory; the comma, a litteral, must be present
  • bold 0.5ms, thin as the ms values are not {{xref_csslength()}}

Double ampersand

Separating two or more components by a double ampersand, &&, means that all these entities are mandatory but may appear in any order.

bold && <length>

This example matches the following values:

  • bold 1em
  • bold 0
  • 2.5cm bold
  • 3vh bold

But not:

  • bold as both components must appear in the value.
  • bold 1em bold as both components must appear only one time.
Note: juxtaposition has precedence over the double ampersand, meaning that bold thin && <length> describes bold thin <length> or <length> bold thin but not bold <length> thin.

Double bar

Separating two or more components by a double bar, ||, means that all entities are options: at least one of them must be present, and they may appear in any order. Typically this is used to define the different values of a shorthand property.

<'border-width'> || <'border-style'> || <'border-color'>

This example matches the following values:

  • 1em solid blue
  • blue 1em
  • solid 1px yellow

But not:

  • blue yellow as a component must appear at most one single time.
  • bold as it isn't a keyword allowed as value of any of the entity.
Note: the double ampersand has precedence over the double bar, meaning that bold || thin && <length> describes bold, thin, <length>, bold thin, <length> bold, or thin <length> bold but not bold <length> bold thin as bold, if not omitted, must be placed before or after the whole thin && <length> component.

Single bar

Separating two or more entities by a single bar, |, means that all entities are exclusive options: exactly one of these options must be present. This is typically used to separate a list of possible keywords.

<percentage> | <length> | left | center | right | top | bottom

This example matches the following values:

  • 3%
  • 0
  • 3.5em
  • left
  • center
  • right
  • top
  • bottom

But not:

  • center 3% as only one of the component must be present.
  • 3em 4.5em as an component must be present at most one time.

Brackets

Brackets enclose several entities, composers and multiplier and transform them as a single entity. They are used to group elements to bypass the precedence rules.

bold [ thin && <length> ]

This example matches the following values:

  • bold thin 2vh
  • bold 0 thin
  • bold thin 3.5em

But not:

  • thin bold 3em as bold is juxtaposed with the entity defined by the brackets, it must appear before it.

Component value multipliers

A multiplier is a sign that indicate how many time a preceding entity can be repeated. Without a multiplier, an entity must appear exactly one time.

Note that multipliers cannot be added and have all precedence over combinators.

Asterisk (*)

The asterisk multiplier indicates that the entity may appear zero, one or several times.

bold smaller*

This example matches the following values:

  • bold
  • bold smaller
  • bold smaller smaller
  • bold smaller smaller smaller and so on.

But not:

  • smaller as bold is juxtaposed and must appear before the eventual smaller keyword.

Plus (+)

The plus multiplier indicates that the entity may appear one or several times.

bold smaller+

This example matches the following values:

  • bold smaller
  • bold smaller smaller
  • bold smaller smaller smaller and so on.

But not:

  • bold as smaller must appear at least one time.
  • smaller as bold is juxtaposed and must appear before the eventual smaller keyword.

Question mark (?)

The question mark multiplier indicates that the entity is optional and must appear zero or one time.

bold smaller?

This example matches the following values:

  • bold
  • bold smaller

But not:

  • bold smaller smaller as smaller must appear at most one time.
  • smaller as bold is juxtaposed and must appear before the eventual smaller keyword.

Curly braces ({ })

The curly braces, enclosing two integers separated by a comma, A and B, indicate that the entity must appear at least A times and at most B times.

bold smaller{1,3}

This example matches the following values:

  • bold smaller
  • bold smaller smaller
  • bold smaller smaller smaller

But not:

  • bold as smaller must appear at least one time.
  • bold smaller smaller smaller smaller as smaller must appear at most one time.
  • smaller as bold is juxtaposed and must appear before the eventual smaller keyword

Hash mark (#)

The hash mark multiplier indicates that the entity may be repeated one or more times (like the plus multiplier) but each occurence is separated by a comma (',').

bold smaller#

This example matches the following values:

  • bold smaller
  • bold smaller, smaller
  • bold smaller, smaller, smaller and so on.

But not:

  • bold as smaller must appear at least one time.
  • bold smaller smaller smaller as the different occurence of smaller must be separated by commas.
  • smaller as bold is juxtaposed and must appear before the eventual smaller keyword.

Summary

Sign Name Description Example
Combinators
  Juxtaposition Entities are mandatory and should appear in that order solid <length>
&& Double ampersand Entities are mandatory but may appear in any order <length> && <string>
|| Double bar At least one of the entities must be present, and they may appear in any order. <'border-image-outset'> || <'border-image-slice'>
| Single bar Exactly one of the entities must be present smaller | small | normal | big | bigger
[ ] Brackets Group elements to bypass the precedence rules bold [ thin && <length> ]
Multipliers
  No multiplier Exactly 1 times solid
* Asterisk 0 or more times bold smaller*
+ Plus sign 1 or more times bold smaller+
? Question mark 0 or 1 time (that is optional) bold smaller?
{A,B} Curly braces At least A times, at most B times bold smaller{1,3}
# Hash mark 1 or more times, but each occurrence separated by a comma (',') bold smaller#

Specifications

Specification Status Comment
{{ SpecName('CSS3 Values', '#value-defs', 'Value definition syntax') }} {{ Spec2('CSS3 Values') }} From {{ SpecName('CSS2.1', 'about.html#value-defs', 'Value definition syntax') }}, adds the hash mark multiplier.
{{ SpecName('CSS2.1', 'about.html#value-defs', 'Value definition syntax') }} {{ Spec2('CSS2.1') }} From {{ SpecName('CSS1', '#notation-for-property-values', 'Value definition syntax') }}, adds the double ampersand combinator.
{{SpecName('CSS1', '#notation-for-property-values', 'Value definition syntax') }} {{ Spec2('CSS1') }} Initial definition.

See also

  • {{ CSS_key_concepts() }}

Revision Source

<p>{{ CSSRef() }}</p>
<p>A formal grammar, the <strong>CSS value definition syntax</strong>, is used for defining the set of valid values that a CSS property or function. In addition to this syntax, the set of valid values can be further restricted by semantic constraints (like, for a number, to be strictly positive).</p>
<p>The definition syntax describes which are allowed and how they interact between them. A component can be a <em>keyword</em>, some characters considered as a <em>litteral</em>, or a value of a given CSS data type or of another CSS property.</p>
<h2 id="Component_value_types">Component value types</h2>
<h3 id="Keywords">Keywords</h3>
<h4 id="Generic_keywords">Generic keywords</h4>
<p>A keyword with a predefined meaning appears litterally, without quote: e.g. <code>auto</code>, <code>smaller</code> or <code>ease-in</code>.</p>
<h4 id="The_specific_case_of_inherit_and_initial">The specific case of <code>inherit</code> and <code>initial</code></h4>
<p>All CSS properties accept the keywords <code>inherit</code> and <code>initial</code> that are defined CSS-wide. They are not shown in the value definition, and are implicitly defined.</p>
<h3 id="Litterals">Litterals</h3>
<p>In CSS a few characters can appear on their own, like the slash ('<code>/</code>') or the comma ('<code>,</code>'), and are used in properties to separate part of it. The comma is often used to separate values in enumeration, or parameters in mathematical-like functions, the slash often separate semantically different part of the value but with a common syntax. Typically, the slash is sometimes used in shorthand properties to separate components of the same types but coming from different properties.</p>
<p>Both symbol appear litteraly in a value definition.</p>
<h3 id="Data_types">Data types</h3>
<h4 id="Basic_data_types">Basic data types</h4>
<p>Some kind of data are used throughout CSS and are defined once for all in the specification. Called <em>basic data types</em>, they are represented with their name surrounded by the symbol '<code>&lt;</code>' and '<code>&gt;</code>': {{ xref_cssangle() }}, {{ xref_cssstring() }}, …</p>
<h4 id="Non-terminal_data_types">Non-terminal data types</h4>
<p>Less common data types, called <em>non-terminal data types</em>, are also surrounded&nbsp; by '<code>&lt;</code>' and '<code>&gt;</code>'.</p>
<p>Non-terminal data types are of two kinds:</p>
<ul>
  <li>data types <em>sharing the same name of a property</em>, put between quotes. In this case the data type shares the same set of value than the property. They are often used in the definition of shorthand properties.</li>
  <li>data type <em>not sharing the same name of a property</em>. These data types are very close to the basic data types. They only differ from the basic data types in the physical location fo their definition: in this case the definition is usually physically very close to the definition of the property using them.</li>
</ul>
<h2 id="Component_value_combinators">Component value combinators</h2>
<h3 id="Juxtaposition">Juxtaposition</h3>
<p>Placing several keywords, litterals, or data types, one next to the other only separated by one or several spaces is called <em>juxtaposition</em>. All juxtaposed components are <u>mandatory and should appear in this very same order</u>.</p>
<pre class="syntaxbox">
bold &lt;length&gt; , thin
</pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold 1em, thin</code></li>
  <li><code>bold 0, thin</code></li>
  <li><code>bold 2.5cm, thin</code></li>
  <li><code>bold 3vh, thin</code></li>
</ul>
<p>But not:</p>
<ul>
  <li><code>thin 1em, bold</code> as the entities must be in the expressed order</li>
  <li><code>bold 1em thin</code> as the entities are mandatory; the comma, a litteral, must be present</li>
  <li><code>bold 0.5ms, thin</code> as the <code>ms</code> values are not {{xref_csslength()}}</li>
</ul>
<h3 id="Double_ampersand">Double ampersand</h3>
<p>Separating two or more components by a <em>double ampersand</em>, <code>&amp;&amp;</code>, means that all these entities are <u>mandatory but may appear in any order</u>.</p>
<pre class="syntaxbox">
bold &amp;&amp; &lt;length&gt;
</pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold 1em</code></li>
  <li><code>bold 0</code></li>
  <li><code>2.5cm bold</code></li>
  <li><code>3vh bold</code></li>
</ul>
<p>But not:</p>
<ul>
  <li><code>bold</code> as both components must appear in the value.</li>
  <li><code>bold 1em bold</code> as both components must appear only one time.</li>
</ul>
<div class="note">
  <strong>Note:</strong> juxtaposition has precedence over the double ampersand, meaning that <code>bold thin &amp;&amp; &lt;length&gt;</code> describes <code>bold thin &lt;length&gt;</code> or <code>&lt;length&gt;</code><code> bold thin</code> but not <code>bold &lt;length&gt;</code><code> thin</code>.</div>
<h3 id="Double_bar">Double bar</h3>
<p>Separating two or more components by a <em>double bar</em>, <code>||</code>, means that all entities are options: <u>at least one of them must be present, and they may appear in any order</u>. Typically this is used to define the different values of a <a href="/en-US/docs/CSS/Shorthand_properties" title="/en-US/docs/CSS/Shorthand_properties">shorthand property</a>.</p>
<pre class="syntaxbox">
&lt;'border-width'&gt; || &lt;'border-style'&gt; || &lt;'border-color'&gt;
</pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>1em solid blue</code></li>
  <li><code>blue 1em</code></li>
  <li><code>solid 1px yellow</code></li>
</ul>
<p>But not:</p>
<ul>
  <li><code>blue</code> <code>yellow</code> as a component must appear at most one single time.</li>
  <li><code>bold</code> as it isn't a keyword allowed as value of any of the entity.</li>
</ul>
<div class="note">
  <strong>Note:</strong> the double ampersand has precedence over the double bar, meaning that <code>bold || thin &amp;&amp; &lt;length&gt;</code> describes <code>bold</code>, <code>thin</code>, <code>&lt;length&gt;</code>, <code>bold thin</code>, <code>&lt;length&gt; bold</code>, or <code>thin &lt;length&gt; bold</code> but not <code>bold &lt;length&gt;</code><code> bold thin</code> as bold, if not omitted, must be placed before or after the whole <code>thin &amp;&amp; &lt;length&gt;</code> component.</div>
<h3 id="Single_bar">Single bar</h3>
<p>Separating two or more entities by a <em>single bar</em>, <code>|</code>, means that all entities are exclusive options: <u>exactly one of these options must be present</u>. This is typically used to separate a list of possible keywords.</p>
<pre class="syntaxbox">
&lt;percentage&gt; | &lt;length&gt; | left | center | right | top | bottom</pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>3%</code></li>
  <li><code>0</code></li>
  <li><code>3.5em</code></li>
  <li><code>left</code></li>
  <li><code>center</code></li>
  <li><code>right</code></li>
  <li><code>top</code></li>
  <li><code>bottom</code></li>
</ul>
<p>But not:</p>
<ul>
  <li><code>center 3%</code> as only one of the component must be present.</li>
  <li><code>3em 4.5em</code> as an component must be present at most one time.</li>
</ul>
<h3 id="Brackets">Brackets</h3>
<p><em>Brackets</em> enclose several entities, composers and multiplier and transform them as a single entity. They are used to <u>group elements to bypass the precedence rules</u>.</p>
<pre class="syntaxbox">
<code>bold [ thin &amp;&amp; &lt;length&gt; ]</code></pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold thin 2vh</code></li>
  <li><code>bold 0 thin</code></li>
  <li><code>bold thin 3.5em</code></li>
</ul>
<p>But not:</p>
<ul>
  <li><code>thin bold 3em</code> as <code>bold</code> is juxtaposed with the entity defined by the brackets, it must appear before it.</li>
</ul>
<h2 id="Component_value_multipliers">Component value multipliers</h2>
<p>A multiplier is a sign that indicate how many time a preceding entity can be repeated. Without a multiplier, an entity must appear exactly one time.</p>
<p>Note that multipliers cannot be added and have all precedence over combinators.</p>
<h3 id="Asterisk_(*)">Asterisk (<code>*</code>)</h3>
<p>The <em>asterisk multiplier</em> indicates that the entity may appear <u>zero, one or several times</u>.</p>
<pre class="syntaxbox">
<code>bold smaller*</code></pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold</code></li>
  <li><code>bold smaller</code></li>
  <li><code>bold smaller smaller</code></li>
  <li><code>bold smaller smaller smaller</code> and so on.</li>
</ul>
<p>But not:</p>
<ul>
  <li><code>smaller</code> as <code>bold</code> is juxtaposed and must appear before the eventual <code>smaller</code> keyword.</li>
</ul>
<h3 id="Plus_(.2B)">Plus (<code>+</code>)</h3>
<p>The <em>plus multiplier</em> indicates that the entity may appear <u>one or several times</u>.</p>
<pre class="syntaxbox">
<code>bold smaller+</code></pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold smaller</code></li>
  <li><code>bold smaller smaller</code></li>
  <li><code>bold smaller smaller smaller</code> and so on.</li>
</ul>
<p>But not:</p>
<ul>
  <li><code>bold</code> as <code>smaller</code> must appear at least one time.</li>
  <li><code>smaller</code> as <code>bold</code> is juxtaposed and must appear before the eventual <code>smaller</code> keyword.</li>
</ul>
<h3 id="Question_mark_(.3F)">Question mark (<code>?</code>)</h3>
<p>The <em>question mark multiplier</em> indicates that the entity is optional and <u>must appear zero or one time</u>.</p>
<pre class="syntaxbox">
<code>bold smaller?</code></pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold </code></li>
  <li><code>bold smaller</code></li>
</ul>
<p>But not:</p>
<ul>
  <li><code>bold smaller smaller</code> as <code>smaller</code> must appear at most one time.</li>
  <li><code>smaller</code> as <code>bold</code> is juxtaposed and must appear before the eventual <code>smaller</code> keyword.</li>
</ul>
<h3 id="Curly_braces_(.7B_.7D)">Curly braces (<code>{ }</code>)</h3>
<p>The <em>curly braces</em>, enclosing two integers separated by a comma, A and B, indicate that the entity <u>must appear at least A times and at most B times</u>.</p>
<pre class="syntaxbox">
<code>bold smaller{1,3}</code></pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold smaller</code></li>
  <li><code>bold smaller </code><code>smaller</code></li>
  <li><code>bold </code><code>smaller </code><code>smaller </code><code>smaller</code></li>
</ul>
<p>But not:</p>
<ul>
  <li><code>bold </code>as <code>smaller</code> must appear at least one time.</li>
  <li><code>bold </code><code>smaller </code><code>smaller </code><code>smaller </code><code>smaller</code> as <code>smaller</code> must appear at most one time.</li>
  <li><code>smaller</code> as <code>bold</code> is juxtaposed and must appear before the eventual <code>smaller</code> keyword</li>
</ul>
<h3 id="Hash_mark_(.23)">Hash mark (<code>#</code>)</h3>
<p>The <em>hash mark</em><em> multiplier</em> indicates that the entity may be repeated <u>one or more times</u> (like the <em>plus multiplier</em>) but each occurence is <u>separated by a comma</u> ('<code>,</code>').</p>
<pre class="syntaxbox">
<code>bold smaller#</code></pre>
<p>This example matches the following values:</p>
<ul>
  <li><code>bold smaller</code></li>
  <li><code>bold smaller, smaller</code></li>
  <li><code>bold smaller, smaller, smaller</code> and so on.</li>
</ul>
<p>But not:</p>
<ul>
  <li><code>bold</code> as <code>smaller</code> must appear at least one time.</li>
  <li><code>bold smaller smaller smaller</code> as the different occurence of <code>smaller</code> must be separated by commas.</li>
  <li><code>smaller</code> as <code>bold</code> is juxtaposed and must appear before the eventual <code>smaller</code> keyword.</li>
</ul>
<h2 id="Summary">Summary</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Sign</th>
      <th scope="col">Name</th>
      <th scope="col">Description</th>
      <th scope="col">Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th colspan="4">Combinators</th>
    </tr>
    <tr>
      <td>&nbsp;</td>
      <td>Juxtaposition</td>
      <td>Entities are mandatory and should appear in that order</td>
      <td><code>solid &lt;length&gt;</code></td>
    </tr>
    <tr>
      <td><code>&amp;&amp;</code></td>
      <td>Double ampersand</td>
      <td>Entities are mandatory but may appear in any order</td>
      <td><code>&lt;length&gt; &amp;&amp; &lt;string&gt;</code></td>
    </tr>
    <tr>
      <td><code>||</code></td>
      <td>Double bar</td>
      <td>At least one of the entities must be present, and they may appear in any order.</td>
      <td><code>&lt;'border-image-outset'&gt; || &lt;'border-image-slice'&gt;</code></td>
    </tr>
    <tr>
      <td><code>|</code></td>
      <td>Single bar</td>
      <td>Exactly one of the entities must be present</td>
      <td><code>smaller | small | normal | big | bigger</code></td>
    </tr>
    <tr>
      <td><code>[ ]</code></td>
      <td>Brackets</td>
      <td>Group elements to bypass the precedence rules</td>
      <td><code>bold [ thin &amp;&amp; &lt;length&gt; ]</code></td>
    </tr>
    <tr>
      <th colspan="4">Multipliers</th>
    </tr>
    <tr>
      <td>&nbsp;</td>
      <td>No multiplier</td>
      <td>Exactly 1 times</td>
      <td><code>solid</code></td>
    </tr>
    <tr>
      <td><code>*</code></td>
      <td>Asterisk</td>
      <td>0 or more times</td>
      <td><code>bold smaller*</code></td>
    </tr>
    <tr>
      <td><code>+</code></td>
      <td>Plus sign</td>
      <td>1 or more times</td>
      <td><code>bold smaller+</code></td>
    </tr>
    <tr>
      <td><code>?</code></td>
      <td>Question mark</td>
      <td>0 or 1 time (that is <em>optional)</em></td>
      <td><code>bold smaller?</code></td>
    </tr>
    <tr>
      <td><code>{A,B}</code></td>
      <td>Curly braces</td>
      <td>At least <code>A</code> times, at most <code>B</code> times</td>
      <td><code>bold smaller{1,3}</code></td>
    </tr>
    <tr>
      <td><code>#</code></td>
      <td>Hash mark</td>
      <td>1 or more times, but each occurrence separated by a comma ('<code>,</code>')</td>
      <td><code>bold smaller#</code></td>
    </tr>
  </tbody>
</table>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
    <tr>
      <td>{{ SpecName('CSS3 Values', '#value-defs', 'Value definition syntax') }}</td>
      <td>{{ Spec2('CSS3 Values') }}</td>
      <td>From {{ SpecName('CSS2.1', 'about.html#value-defs', 'Value definition syntax') }}, adds the hash mark multiplier.</td>
    </tr>
    <tr>
      <td>{{ SpecName('CSS2.1', 'about.html#value-defs', 'Value definition syntax') }}</td>
      <td>{{ Spec2('CSS2.1') }}</td>
      <td>From {{ SpecName('CSS1', '#notation-for-property-values', 'Value definition syntax') }}, adds the double ampersand combinator.</td>
    </tr>
    <tr>
      <td>{{SpecName('CSS1', '#notation-for-property-values', 'Value definition syntax') }}</td>
      <td>{{ Spec2('CSS1') }}</td>
      <td>Initial definition.</td>
    </tr>
  </tbody>
</table>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{ CSS_key_concepts() }}</li>
</ul>
Revert to this revision