CSS Typed Object Model API
==========================

The CSS Typed Object Model API simplifies CSS property manipulation by exposing CSS values as typed JavaScript objects rather than strings. This not only simplifies CSS manipulation, but also lessens the negative impact on performance as compared to `HTMLElement.style`.

Generally, CSS values can be read and written in JavaScript as strings, which can be slow and cumbersome. CSS Typed Object Model API provides interfaces to interact with underlying values, by representing them with specialized JS objects that can be manipulated and understood more easily and more reliably than string parsing and concatenation. This is easier for authors (for example, numeric values are reflected with actual JS numbers, and have unit-aware mathematical operations defined for them). It is also generally faster, as values can be directly manipulated and then cheaply translated back into underlying values without having to both build and parse strings of CSS.

CSS Typed OM both allows for the performant manipulation of values assigned to CSS properties while enabling maintainable code that is both more understandable and easier to write.

Interfaces
----------

### `CSSStyleValue`

The `CSSStyleValue` interface of the CSS Typed Object Model API is the base class of all CSS values accessible through the Typed OM API. An instance of this class may be used anywhere a string is expected.

`CSSStyleValue.parse()`

The parse() method of the CSSStyleValue interface allows a CSSNumericValue to be constructed from a CSS string. It sets a specific CSS property to the specified values and returns the first value as a CSSStyleValue object.

`CSSStyleValue.parseAll()`

The parseAll() method of the CSSStyleValue interface sets all occurrences of a specific CSS property to the specified value and returns an array of CSSStyleValue objects, each containing one of the supplied values.

### `StylePropertyMap`

The `StylePropertyMap` interface of the CSS Typed Object Model API provides a representation of a CSS declaration block that is an alternative to CSSStyleDeclaration.

`StylePropertyMap.set()`

Method of StylePropertyMap interface that changes the CSS declaration with the given property to the value given.

`StylePropertyMap.append()`

Method that adds a new CSS declaration to the StylePropertyMap with the given property and value.

`StylePropertyMap.delete()`

Method that removes the CSS declaration with the given property from the StylePropertyMap.

`StylePropertyMap.clear()`

Method that removes all declarations in the StylePropertyMap.

### `CSSUnparsedValue`

The `CSSUnparsedValue` interface of the CSS Typed Object Model API represents property values that reference custom properties. It consists of a list of string fragments and variable references.

`CSSUnparsedValue()` constructor

Creates a new CSSUnparsedValue object which represents property values that reference custom properties.

`CSSUnparsedValue.entries()`

Method returning an array of a given object's own enumerable property [key, value] pairs in the same order as that provided by a for...in loop (the difference being that a for-in loop enumerates properties in the prototype chain as well).

`CSSUnparsedValue.forEach()`

Method executing a provided function once for each element of the CSSUnparsedValue.

`CSSUnparsedValue.keys()`

Method returning a new *array iterator* object that contains the keys for each index in the array.

### `CSSKeywordValue` Serialization

The `CSSKeywordValue` interface of the CSS Typed Object Model API creates an object to represent CSS keywords and other identifiers.

`CSSKeywordValue()` constructor

Constructor creates a new `CSSKeywordValue()` object which represents CSS keywords and other identifiers.

`CSSKeywordValue.value()`

Property of the CSSKeywordValue interface returning or setting the value of the CSSKeywordValue.

CSSStyleValue Interfaces
------------------------

CSSStyleValue is the base class through which all CSS values are expressed. Subclasses include:

`CSSImageValue` objects

An interface representing values for properties that take an image, for example `background-image`, `list-style-image`, or `border-image-source`.

`CSSKeywordValue`

An interface which creates an object to represent CSS keywords and other identifiers. When used where a string is expected, it will return the value of CSSKeyword.value.

`CSSMathValue`

A tree of subclasses representing numeric values that are more complicated than a single value and unit, including:

* `CSSMathInvert` - represents a CSS `calc()` value used as `calc(1 / <value>)`.
* `CSSMathMax` - represents the CSS `max()` function.
* `CSSMathMin` - represents the CSS `min()` function.
* `CSSMathNegate` - negates the value passed into it.
* `CSSMathProduct` - represents the result obtained by calling `add()`, `sub()`, or `toSum()` on `CSSNumericValue`.
* `CSSMathSum` - represents the result obtained by calling `add()`, `sub()`, or `toSum()` on `CSSNumericValue`.

`CSSNumericValue`

An interface representing operations that all numeric values can perform, including:

* `CSSNumericValue.add` - Adds supplied numbers to the `CSSNumericValue`.
* `CSSNumericValue.sub` - Subtracts supplied numbers to the `CSSNumericValue`.
* `CSSNumericValue.mul` - Multiplies supplied numbers to the `CSSNumericValue`.
* `CSSNumericValue.div` - Divides a supplied number by other numbers, throwing an error if 0.
* `CSSNumericValue.min` - Returns the minimum value passed
* `CSSNumericValue.max` - Returns the maximum value passed
* `CSSNumericValue.equals` - Returns true if all the values are the exact same type and value, in the same order. Otherwise, false
* `CSSNumericValue.to` - Converts `value` into another one with the specified *unit.*
* `CSSNumericValue.toSum`
* `CSSNumericValue.type`
* `CSSNumericValue.parse` - Returns a number parsed from a CSS string

`CSSPositionValue`

Represents values for properties that take a position, for example object-position.

`CSSTransformValue`

An interface representing a list of `transform` list values. They "contain" one or more `CSSTransformComponent`s, which represent individual `transform` function values.

`CSSUnitValue`

An interface representing numeric values that can be represented as a single unit, or a named number and percentage.

`CSSUnparsedValue`

Represents property values that reference custom properties. It consists of a list of string fragments and variable references.

Specifications
--------------

| Specification |
| --- |
| CSS Typed OM Level 1 # stylevalue-objects |
| CSS Typed OM Level 1 # the-stylepropertymap |
| CSS Typed OM Level 1 # cssunparsedvalue |
| CSS Typed OM Level 1 # keywordvalue-objects |

Browser compatibility
---------------------

### api.CSSStyleValue

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.StylePropertyMap

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.CSSUnparsedValue

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.CSSKeywordValue

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* CSS Painting API
* Using the CSS Typed Object Model
* CSS Houdini