Custom properties (--*): CSS variables

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2017.

Property names that are prefixed with --, like --example-name, represent custom properties that contain a value that can be used in other declarations using the var() function.

Custom properties are scoped to the element(s) they are declared on, and participate in the cascade: the value of such a custom property is that from the declaration decided by the cascading algorithm.

Initial valuesee prose
Applies toall elements
Inheritedyes
Computed valueas specified with variables substituted
Animation typediscrete

Syntax

css
--some-keyword: left;
--some-color: #123456;
--some-complex-value: 3px 6px rgb(20 32 54);
<declaration-value>

This value matches any sequence of one or more tokens, so long as the sequence does not contain any disallowed token. It represents the entirety of what a valid declaration can have as its value.

Note: Custom property names are case sensitive — --my-color will be treated as a separate custom property to --My-color.

Example

Basic example

HTML

html
<p id="firstParagraph">
  This paragraph should have a blue background and yellow text.
</p>
<p id="secondParagraph">
  This paragraph should have a yellow background and blue text.
</p>
<div id="container">
  <p id="thirdParagraph">
    This paragraph should have a green background and yellow text.
  </p>
</div>

CSS

css
:root {
  --first-color: #1166ff;
  --second-color: #ffff77;
}

#firstParagraph {
  background-color: var(--first-color);
  color: var(--second-color);
}

#secondParagraph {
  background-color: var(--second-color);
  color: var(--first-color);
}

#container {
  --first-color: #229900;
}

#thirdParagraph {
  background-color: var(--first-color);
  color: var(--second-color);
}

Result

Registering custom properties with @property

In this example, we use the @property at-rule to register a custom property.

HTML

Our HTML includes an ordered list (<ol>) containing three list items (<li>).

html
<ol>
  <li class="one">Item one</li>
  <li class="two">Item two</li>
  <li class="three">Item three</li>
</ol>

CSS

We use the @property at-rule to register two custom properties.

css
@property --itemSize {
  syntax: "<length> | <percentage>";
  inherits: true;
  initial-value: 200px;
}

@property --borderWidth {
  syntax: "<length>";
  inherits: false;
  initial-value: 10px;
}

We try to override the custom property values. The values set on .two are valid while the values set on .three are invalid.

css
ol {
  --itemSize: 100px;
  --borderWidth: 1px;
}
.two {
  --itemSize: initial;
  --borderWidth: inherit;
}
.three {
  --itemSize: large;
  --borderWidth: 3%;
}

We use the two custom properties to style the items, setting the border and width for all the items at once:

css
li {
  width: var(--itemSize);
  border: var(--borderWidth) solid red;
  background-color: yellow;
  margin-bottom: 10px;
}

Results

The --itemSize property is inheritable; the --borderWidth is not. The properties are set on the ol parent, overriding the default values defined in their registration. Item one inherits the size but not the border width from the OL. The global keywords, declared for .two, are valid for <length>, so are used. The values in .three are invalid ("large" is not a <length-percentage> and 3% is not a <length>). See

Specifications

Specification
CSS Custom Properties for Cascading Variables Module Level 1
# defining-variables

Browser compatibility

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
--*
Chrome – Full support
Chrome 49 (Release date: 2016-03-02)
footnote Full support
Edge – Full support
Edge 15 (Release date: 2017-04-05)
footnote Full support
Firefox – Full support
Firefox 31 (Release date: 2014-07-22)
footnote Full support
Opera – Full support
Opera 36 (Release date: 2016-03-15)
footnote Full support
Safari – Full support
Safari 9.1 (Release date: 2016-03-21)
footnote Full support
Chrome Android – Full support
Chrome Android 49 (Release date: 2016-03-09)
footnote Full support
Firefox for Android – Full support
Firefox for Android 31 (Release date: 2014-07-22)
footnote Full support
Opera Android – Full support
Opera Android 36 (Release date: 2016-03-31)
footnote Full support
Safari on iOS – Full support
Safari on iOS 9.3 (Release date: 2016-03-21)
footnote Full support
Samsung Internet – Full support
Samsung Internet 5 (Release date: 2016-12-15)
footnote Full support
WebView Android – Full support
WebView Android 49 (Release date: 2016-03-09)
footnote Full support
WebView on iOS – Full support
WebView on iOS 9.3 (Release date: 2016-03-21)
footnote Full support

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

See also