CSS properties and values API
=============================

 The **CSS properties and values API** module defines a method for registering new CSS properties, defining the property's data type, inheritance behavior, and, optionally, an initial value.
 This API expands on CSS custom properties for cascading variables module, which allows authors to define custom properties in CSS using two dash syntax (`--`).
 The CSS properties and values API is part of the CSS Houdini umbrella of APIs.

 Custom properties let you reuse values across a project to simplify complex or repetitive stylesheets.
 Basic custom properties are defined in the CSS custom properties for cascading variables module.
 The CSS properties and values API expands on that module, enabling adding metadata to custom properties using CSS with the `@property` at-rule or, alternatively, using JavaScript's `CSS.registerProperty` method.

Whether registered with CSS or JavaScript, setting metadata on custom properties provides for an expected data type that the browser can use depending on the context, defines an initial value, and lets you control inheritance.

CSS properties and values API custom property registration is more robust than the more basic CSS cascading variable custom property declaration, especially when it comes to transitioning and animating values as browsers can interpolate between custom values of this type, whereas properties that use two dash syntax (`--`) behave more like a string substitution.

Properties and values API in action
-----------------------------------

To see how custom properties and values can be used via API, hover over the box below.
```

CSS.registerProperty({
  name: "--stop-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "cornflowerblue",
});
```


```
.box {
  padding: 1rem;
  width: 90%;
  height: 4rem;
  font-family: sans-serif;
  font-size: large;
  color: white;
  border-radius: 0.5rem;
}

.box {
  background: linear-gradient(to right, var(--stop-color), lavenderblush);
  transition: --stop-color 2s;
}

.box:hover {
  --stop-color: aquamarine;
}
```


```
<div class="box"><p>Linear gradient with transition</p></div>
```


 The box has a backround consisting of a linear gradient from `--stop-color` (the custom property) to `lavenderblush`.
 The value of `--stop-color` is set to `cornflowerblue` at first, but when you hover over the box, `--stop-color` transitions to `aquamarine` over two seconds (`linear-gradient(to right, aquamarine, lavenderblush)`).

Reference
---------

### At-rules

* `@property`
    + syntax descriptor
        - `+` and `#` multipliers
        - `|` combinator
    + inherits descriptor
    + initial-value descriptor
### Interfaces and APIs

* `CSSPropertyRule`
* `CSS.registerProperty()`
Guides
------

Using the CSS properties and values API

Explains how to register custom properties in CSS and JavaScript, with hints on handling undefined and invalid values, fallbacks, and inheritance.

Houdini APIs

Explains what CSS Houdini is and its advantages, along with a list of available APIs and their statuses.

Related concepts
----------------

* `var()`
* CSSRule
* CSSStyleValue
* CSS scoping
* Using shadow DOM
* CSS Typed Object Model API
* CSS Painting API
* Worklet
Specifications
--------------

| Specification |
| --- |
| CSS Properties and Values API Level 1  |

See also
--------

* CSS cascade and inheritance
* CSS scoping module
* Using shadow DOM
* CSS Painting API module
* Worklet interface
* CSS `env()`
* CSS Typed Object Model