CSS definitions of the web platform

This package contains a consolidated list of CSS features defined across specs, scraped from the latest versions of web platform specifications in webref. Fixes are applied to ensure that guarantees hold, including the ability to parse syntaxes associated with CSS features with CSSTree.

Important: If you're migrating from version 6, see the changelog for "How to upgrade" considerations.

API

Two async methods are exposed: listAll() and index(). They both resolve with an object that lists CSS features by feature type: atrules, functions, properties, selectors and types.

The difference between the two functions is that, under each feature type, listAll() returns an array of features, whereas index() returns an object indexed by feature name to ease direct lookups (and transition from mdn/data. Both functions return the same features.

Example using listAll():

const css = require('@webref/css');

const { atrules, functions, properties, selectors, types } = await css.listAll();

for (const feature of functions) {
  // do something with the object that describes the CSS function
}

Example using index():

const css = require('@webref/css');

const { atrules, functions, properties, selectors, types } = await css.index();

// Do something with the object that describes the abs() function
const abs = functions['abs()'];

Each CSS feature is described by:

• a name key that contains the name of the feature
• an href key that contains the URL (with a fragment) of the CSS spec that defines the feature

Many CSS features also have a syntax key that describes the syntax of the feature, as defined in the spec. This syntax can be parsed with the CSSTree Value Definition Syntax parser. Example:

const css = require('@webref/css');
const { definitionSyntax } = require('css-tree');

const { properties } = await css.index();
const ast = definitionSyntax.parse(properties['flex'].syntax);
// do something with the abstract syntax tree

Additional keys may be set depending on the type of the CSS feature. For example:

• At-rules have a descriptors key that contains the list of descriptors defined for the given at-rule. That list may not be exhaustive. For example, it does not contain descriptors that are only implicitly defined in specs, such as families of properties that some at-rules (e.g, @position-try) accept as descriptors.
• Functions and types that are scoped to a property or other feature have a for key that contains the list of scoping features for that feature. A scoping feature may be a property, a function or a type. When the scoping feature is a type, its name in the for key is enclosed between < and >.
• Properties have a styleDeclaration key that contains the list of IDL attribute names that the property generates. A number of other keys may be set to describe the property's initial value, animation type and other parameters.

Additional notes:

• Features returned by index() are indexed by their feature name, but there are exceptional cases where a given feature is defined differently (with a different syntax) for different scopes. In such cases the feature is indexed by its name completed with for and the name of the first scoping feature to which the definition applies. For example, type() for @function, type() for attr(). As of June 2025, this affects a handful of functions and types.
• When a feature is defined across different levels in the same spec series, the definition from the latest level is used.
• When a property is extended with new values in different specs, href links to the base definition and syntax is the union (using |) of the syntaxes of the base and extended definitions.
• When new descriptors are defined for an at-rule in different specs, descriptors contains the merged list of known descriptors.

Migrating from mdn/data

The structure of the consolidated list of CSS features aligns with CSS data in mdn/data. If you use the index() method, the @webref/css package can almost serve as a drop-in replacement for the mdn/data package for syntaxes, with the following structural nuances:

• mdn/data reports at-rules under an atRules key. @webref/css reports them under an atrules key.
• mdn/data stores syntaxes of functions and types under a separate syntaxes key. @webref/css stores them in their feature definition. If you need to reproduce the syntaxes list, merge the entries under functions and types.
• mdn/data assumes all features are unscoped. @webref/css reports scopes where needed in a for key. Note that a few functions have a different syntax depending on the scope under which they are used.
• @webref/css does not contain information about CSS units.

Beyond structural nuances, differences in content may also affect transition:

• mdn/data contains deprecated features, proprietary features or feature variants that are not defined in specs. @webref/css only contains features defined in specs.
• mdn/data describes features as implemented in main browsers. @webref/css "lives on the edge", listing features and syntaxes from latest levels of CSS specs, regardless of the spec's maturity level and support across browsers.
• mdn/data turns specs prose into syntax when needed, @webref/css only has syntaxes that are explicitly defined in specs. It should be possible to improve the specs, consider submitting missing syntax reports (against the specs themselves if possible, in Webref otherwise).

Guarantees

The following guarantees are provided by this package:

• All syntax values (the syntax keys) can be parsed by the version of CSSTree set in peerDependencies in package.json.
• Feature names (the name keys) are unique per type provided that the for key is also taken into account for functions and types.
• All features have an href key that targets the CSS spec that defines the feature. When the feature is extended across CSS specs, this URL targets the base definition.

Note: there is no guarantee that functions, properties and types referenced by other constructs actually exist. The grammar is known to be incomplete.

Changelog

This file documents breaking changes introduced in major releases of the @webref/css NPM package.

Webref adheres to Semantic Versioning, applied to data. A new major version is released whenever a breaking change is made to the data structure.

v7.0.11 - 2025-09-04

CSS extracts are now consolidated into a single file.

Breaking changes

• A single consolidated css.json file replaces CSS extracts per spec.

How to upgrade

In version 6, listAll() resolved with an object where the keys were spec shortnames, and the values mostly matched the structure of the consolidated object that the function now returns. On top of the consolidation itself, main differences are:

• Functions and types were merged in a values category in version 6, they now appear in separate functions and types categories.
• Functions and types that were scoped to another CSS feature appeared nested under that CSS feature in version 6. They now appear directly under functions and types with a for key that contains the list of scoping features for that feature. A scoping feature may be a property, a function or a type. When the scoping feature is a type, its name in the for key is enclosed between < and >.
• Feature syntaxes were stored in a value key. That key is now named syntax. Actual syntax values are the same as before and can be parsed with CSSTree.
• The shortname of the spec (or specs) that defines a feature is no longer readily available (but note the href key targets the defining spec). If you need the specs' shortnames, please raise an issue to describe your use case.
• The consolidation removes duplicates, merging extended definitions into a single feature. The definition from the latest spec level is used when a feature is defined in more than one level. If you need the definition from earlier levels, please raise an issue to describe your needs!
• Some of the possible values that a CSS feature could take appeared nested under that feature definition in a values key in version 6. Such values are no longer reported in the new version: they were confusing in any case because they did not cover the whole range of values that a feature could take, and could contain values that were not atomic keyword values. Values could be re-introduced when CSS specs are more systematic about them. In the meantime, you will need to parse the feature's syntax (the syntax key) to extract keyword values.

Additionally, the package now also exposes a new index() async method that resolves with an object similar to that returned by listAll(), except that lists of features under each category are indexed by feature names. For scoped features, the feature name is used as identifier when it is unambiguous. If a feature is defined differently for different scopes, the feature name is completed with the name of the first scoping feature to disambiguate. For example, type() for @function, type() for attr().

v6.0.0 - 2022-11-28

Major re-write of CSS extracts listed in the package, following the release of Reffy v11.0.0

Breaking changes

• Arrays are now used throughout instead of indexed objects.
• Function names are no longer enclosed in < and > because they are not defined in specs with these characters (as opposed to types). Beware though, references to functions in value syntax do use enclosing < and > characters.
• The property valuespaces at the root level is now named values. An array is used there as well. The values property lists both function and type definitions that are not namespaced to anything in particular (it used to also contain namespaced definitions).

Added

• Selectors are now reported under a selectors property at the root level.
• Possible values that some definition may take are now reported under a values property directly within the definition.
• Functions and types that are namespaced to some other definition are included in the list of values of that definition.
• Anomalies detected in the spec are now reported under a warnings property at the root of the extract. Four types of anomalies are reported:
  1. Missing definition: when a production rule was found but when the spec does not include a corresponding <dfn> (or when that <dfn> does not have a data-dfn-type attribute that identifies a CSS construct)
  2. Duplicate definition: when the spec defines the same term twice.
  3. Unmergeable definition: when the spec defines the same property twice and both definitions cannot be merged.
  4. Dangling value: when the spec defines a CSS "value" definition (value, function or type) for something and that something cannot be found in the spec
• To distinguish between function, type and value definitions listed in a values property, definitions that appear in a values property have a type property.

Additional notes

• Only namespaced values associated with a definition are listed under its values property. Non-namespaced values are not. For instance, <quote> is not listed as a value of the <content-list> type, even though its value syntax references it. This is to avoid duplicating constructs in the extracts.
• Values are only listed under the deepest definition to which they apply. For instance, open-quote is only listed as a value of <quote> but neither as a value of the <content-list> type that references <quote> nor as a value of the content property that references <content-list>. This is also to avoid duplicating constructs in the extracts.
• Some of the extracts contain things that may look weird at first, but that is "by design". For instance, CSS Will change defines a <custom-ident> value construct whose actual value is the <custom-ident> type construct defined in CSS Values. Having both a namespaced value and a non-namespaced <type> is somewhat common in CSS specs.