From 671fd9830dc9ca913a887be21fb6cf5c290944a7 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 24 Nov 2023 15:12:08 +0100 Subject: [PATCH 01/20] docs(css): add module page for CSS Properties and Values API * link to guides and module pages --- .../guide/index.md | 13 ++ files/en-us/web/css/--_star_/index.md | 3 +- files/en-us/web/css/@property/index.md | 2 + .../web/css/css_cascading_variables/index.md | 92 +++++++- .../css_properties_and_values_api/index.md | 203 ++++++++++++++++++ files/en-us/web/css/env/index.md | 4 +- .../css/using_css_custom_properties/index.md | 3 +- files/en-us/web/css/var/index.md | 3 +- 8 files changed, 315 insertions(+), 8 deletions(-) create mode 100644 files/en-us/web/css/css_properties_and_values_api/index.md diff --git a/files/en-us/web/api/css_properties_and_values_api/guide/index.md b/files/en-us/web/api/css_properties_and_values_api/guide/index.md index e035c91329210dc..f3c519e440c85bf 100644 --- a/files/en-us/web/api/css_properties_and_values_api/guide/index.md +++ b/files/en-us/web/api/css_properties_and_values_api/guide/index.md @@ -2,6 +2,11 @@ title: Using the CSS properties and values API slug: Web/API/CSS_Properties_and_Values_API/guide page-type: guide +browser-compat: + - css.at-rules.property + - css.properties.custom-property.var + - api.CSSPropertyRule + - api.CSS.registerProperty_static --- {{DefaultAPISidebar("CSS Properties and Values API")}}{{SeeCompatTable}} @@ -105,3 +110,11 @@ While not functionally accurate, a good way to think about the difference betwee There are two gotchas when registering a property. The first is that, once a property is registered, there's no way to update it, and trying to re-register it with [JavaScript](/en-US/docs/Web/JavaScript) will throw an error indicating it's already been defined. Second, unlike standard properties, registered properties aren't validated when they're parsed. Rather, they're validated when they're computed. That means both that invalid values won't appear as invalid when inspecting the element's properties, and that including an invalid property after a valid one won't fall back to the valid property. An invalid property will, however, fall back to its registered default. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/css/--_star_/index.md b/files/en-us/web/css/--_star_/index.md index b3c841459af4727..625784040e31154 100644 --- a/files/en-us/web/css/--_star_/index.md +++ b/files/en-us/web/css/--_star_/index.md @@ -86,6 +86,7 @@ Custom properties are scoped to the element(s) they are declared on, and partici ## See also -- [Using CSS variables](/en-US/docs/Web/CSS/Using_CSS_custom_properties) - The {{cssxref("var", "var()")}} function - {{cssxref("@property")}} at-rule +- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) guide +- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module diff --git a/files/en-us/web/css/@property/index.md b/files/en-us/web/css/@property/index.md index 35346fd86a152b7..2998f6afffdc488 100644 --- a/files/en-us/web/css/@property/index.md +++ b/files/en-us/web/css/@property/index.md @@ -130,3 +130,5 @@ For item three, the `--item-size` value gets set to `1000px`. While `1000px` is - [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API) - [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API) - [CSS Houdini](/en-US/docs/Web/Guide/Houdini) +- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) guide +- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module diff --git a/files/en-us/web/css/css_cascading_variables/index.md b/files/en-us/web/css/css_cascading_variables/index.md index cfa1e148a091462..b81313bbcea0733 100644 --- a/files/en-us/web/css/css_cascading_variables/index.md +++ b/files/en-us/web/css/css_cascading_variables/index.md @@ -1,13 +1,79 @@ --- -title: CSS cascading variables +title: CSS custom properties for cascading variables slug: Web/CSS/CSS_cascading_variables page-type: css-module -spec-urls: https://drafts.csswg.org/css-variables/ +browser-compat: + - css.properties.custom-property + - css.properties.custom-property.var --- {{CSSRef}} -The **CSS cascading variables** module adds support for cascading variables in all CSS properties and also lets you create custom properties to define these variables. +The **CSS custom properties for cascading variables** module adds support for cascading variables in for CSS properties and lets you create custom properties to define these variables. + +Custom properties are defined using [two dashes (`--`)](/en-US/docs/Web/CSS/--*) and are subject to the [cascade](/en-US/docs/Web/CSS/Cascade), so they inherit their value from their parent. +The purpose of custom properties is to help manage complex CSS stylesheets by allowing you to define a property's value in one place and reuse that value in multiple declarations across a project. + +A benefit of custom properties is improved readability and semantics. +For example, `--dark-grey-text` and `--dark-footer` are easier to understand than hexadecimal colors such as `#00ff00`, and the context of their use is much more apparent. + +## Example + +The following example shows a + +```html +
+
+

One

+
+
+

Two

+
+

Three

+
+
+
+``` + +```css hidden +body { + font-family: sans-serif; +} + +div, +input, +textarea { + border: 2px black solid; + padding: 4px; + margin: 4px; +} + +.container { + display: grid; + gap: 10px; +} +``` + +```css +/* Define --main-bg-color here */ +.container { + --main-bg-color: cornflowerblue; +} + +/* For each class, set some colors */ +.one { + background-color: var(--main-bg-color); +} +.two { + color: black; + background-color: aquamarine; +} +.three { + background-color: var(--main-bg-color); +} +``` + +{{EmbedLiveSample("",600,360)}} ## Reference @@ -15,6 +81,26 @@ The **CSS cascading variables** module adds support for cascading variables in a - {{cssxref("--*")}} +### Functions + +- {{cssxref("var()")}} + +## Guides + +- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) + ## Specifications {{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade) +- [CSS Properties and Values API](/en-US/docs/Web/CSS/CSS_properties_and_values_API) module +- [CSS `env()`](Web/CSS/env) +- [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API) +- [CSS Houdini](/en-US/docs/Web/Guide/Houdini) diff --git a/files/en-us/web/css/css_properties_and_values_api/index.md b/files/en-us/web/css/css_properties_and_values_api/index.md new file mode 100644 index 000000000000000..1c6e5fd1b55da13 --- /dev/null +++ b/files/en-us/web/css/css_properties_and_values_api/index.md @@ -0,0 +1,203 @@ +--- +title: CSS Properties and Values API +slug: Web/CSS/CSS_properties_and_values_API +page-type: css-module +browser-compat: + - css.at-rules.property + - css.properties.custom-property.var + - api.CSSPropertyRule + - api.CSS.registerProperty_static +--- + +{{CSSRef}} + +The **CSS properties and values API** module is is part of the [CSS Houdini](/en-US/docs/Web/Guide/Houdini) umbrella of APIs and allows authors to define custom properties for cascading variables. +This API expands on [CSS custom properties for cascading variables](Web/CSS/CSS_cascading_variables) which allows authors to define custom properties in CSS using [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*). + +The additional functionality provided by the Properties and Values API is the introduction of control over inheritance, the ability to set initial values, and data type constraints. +Authors can define CSS properties using the [`@property`](/en-US/docs/Web/CSS/@property) at-rule in CSS and the {{domxref('CSS/registerProperty_static', 'CSS.registerProperty')}} interface in JavaScript. + +## Examples + +### Registering custom properties in JavaScript + +Registering custom properties is done using {{domxref('CSS/registerProperty_static', 'CSS.registerProperty')}}. +Because inheritance is disabled, the value `cornflowerblue` set in the parent element is not defined in the scope of the `.child` element, and the initial value of `cornflowerblue` is used: + +```js +window.CSS.registerProperty({ + name: "--custom-bg-color", + syntax: "", + inherits: false, + initialValue: "aquamarine", +}); +``` + +```css hidden +div { + font-family: sans-serif; + width: 200px; + height: 200px; + margin: 10px; + padding: 10px; + border: 2px black solid; +} + +.child { + width: 80%; + height: 80%; +} +``` + +```css +.parent { + --custom-bg-color: cornflowerblue; + background-color: var(--custom-bg-color); +} + +.child { + background-color: var(--custom-bg-color); +} +``` + +```html +
+
+

Custom property registered in JavaScript

+
+
+``` + +{{EmbedLiveSample("",600,260)}} + +### Using the `@property` at-rule in CSS + +The following example shows a custom property (`--box-color`) defined using the `@property` at-rule. +This custom property represents a color data type and has a default value of `cornflowerblue`. +The `inherits: false;` property ensures that the custom property does not inherit its value from its parent. + +The element with the `.child` class has a style declaration that sets its background to the `--box-color` property value. +The value `green` set in the parent element is not defined in the scope of the `.child` element, and the initial value of `cornflowerblue` is used: + +```css hidden live-sample___at-property-no-inheritance +div { + font-family: sans-serif; + width: 200px; + height: 200px; + margin: 10px; + padding: 10px; + border: 2px black solid; + color: white; +} + +.child { + width: 80%; + height: 80%; +} +``` + +```css live-sample___at-property-no-inheritance +@property --box-color { + syntax: ""; + inherits: false; + initial-value: cornflowerblue; +} + +.parent { + --box-color: green; + background-color: var(--box-color); +} + +.child { + background-color: var(--box-color); +} +``` + +```html live-sample___at-property-no-inheritance +
+
+

@property at-rule example

+
+
+``` + +{{EmbedLiveSample("at-property-no-inheritance",600,260)}} + +### Using initial values + +If a custom property is not defined, the initial value can be used as a fallback. +In the following example, a custom property is defined using the `@property` syntax with `cornflowerblue` as the initial value. +The `.parent` element uses this color as its background color while the property is not defined outside of the at-rule. +The initial value is used instead of the background color inherited from its parent: + +```css hidden +div { + font-family: sans-serif; + width: 200px; + height: 200px; + margin: 10px; + padding: 10px; + border: 2px black solid; + color: white; +} + +.child { + width: 80%; + height: 80%; +} +``` + +```css +@property --box-color { + syntax: ""; + inherits: true; + initial-value: cornflowerblue; +} + +.parent { + background-color: var(--box-color); +} +``` + +```html +
+
+

Undefined property value for --box-color

+
+
+``` + +{{EmbedLiveSample("",600,260)}} + +## Reference + +### At-rules + +- {{cssxref("@property")}} + +### Functions + +- {{cssxref("var()")}} + +### Interfaces + +- {{domxref('CSS/registerProperty_static', 'CSS.registerProperty')}} + +## Guides + +- [Using the CSS properties and values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API/guide) + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade) +- [CSS Houdini](/en-US/docs/Web/Guide/Houdini) +- [CSS `env()`](Web/CSS/env) +- [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/css/env/index.md b/files/en-us/web/css/env/index.md index 23da09dcc7fa22d..3755b9638ae4020 100644 --- a/files/en-us/web/css/env/index.md +++ b/files/en-us/web/css/env/index.md @@ -212,8 +212,8 @@ main { ## See also - {{CSSxRef("var", "var(…)")}} -- [CSS Custom Properties for Cascading Variables](/en-US/docs/Web/CSS/CSS_cascading_variables) -- [Custom Properties (--\*)](/en-US/docs/Web/CSS/--*) +- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module +- [Custom properties (--\*): CSS variables](/en-US/docs/Web/CSS/--*) - [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) - [Customize the window controls overlay of your PWA's title bar](https://web.dev/articles/window-controls-overlay) - [Display content in the title bar](https://docs.microsoft.com/microsoft-edge/progressive-web-apps-chromium/how-to/window-controls-overlay) diff --git a/files/en-us/web/css/using_css_custom_properties/index.md b/files/en-us/web/css/using_css_custom_properties/index.md index 6fcfa9f2f85fd6f..300a6f6c1fdf800 100644 --- a/files/en-us/web/css/using_css_custom_properties/index.md +++ b/files/en-us/web/css/using_css_custom_properties/index.md @@ -535,5 +535,6 @@ element.style.setProperty("--my-var", jsVar + 4); - [Custom property syntax](/en-US/docs/Web/CSS/--*) - {{cssxref("@property")}} at-rule -- [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API) - [`var()`](/en-US/docs/Web/CSS/var) +- [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API) +- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module diff --git a/files/en-us/web/css/var/index.md b/files/en-us/web/css/var/index.md index b0dc99f856ffa17..3f523e0bd84f69d 100644 --- a/files/en-us/web/css/var/index.md +++ b/files/en-us/web/css/var/index.md @@ -195,5 +195,6 @@ Since `--main-bg-color` isn't set, the body's `background-color` will fall back ## See also - {{cssxref("env","env(…)")}} – read‑only environment variables controlled by the user‑agent. -- [Using CSS variables](/en-US/docs/Web/CSS/Using_CSS_custom_properties) +- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) - {{cssxref("@property")}} at-rule +- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module From af2ed26d3c5409651916e9a982ed1a726ba97cd1 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 24 Nov 2023 15:20:19 +0100 Subject: [PATCH 02/20] docs(css): remove unnecessary string identifier --- .../en-us/web/css/css_properties_and_values_api/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/files/en-us/web/css/css_properties_and_values_api/index.md b/files/en-us/web/css/css_properties_and_values_api/index.md index 1c6e5fd1b55da13..6a006de28bba62c 100644 --- a/files/en-us/web/css/css_properties_and_values_api/index.md +++ b/files/en-us/web/css/css_properties_and_values_api/index.md @@ -79,7 +79,7 @@ The `inherits: false;` property ensures that the custom property does not inheri The element with the `.child` class has a style declaration that sets its background to the `--box-color` property value. The value `green` set in the parent element is not defined in the scope of the `.child` element, and the initial value of `cornflowerblue` is used: -```css hidden live-sample___at-property-no-inheritance +```css hidden div { font-family: sans-serif; width: 200px; @@ -96,7 +96,7 @@ div { } ``` -```css live-sample___at-property-no-inheritance +```css @property --box-color { syntax: ""; inherits: false; @@ -113,7 +113,7 @@ div { } ``` -```html live-sample___at-property-no-inheritance +```html

@property at-rule example

@@ -121,7 +121,7 @@ div {
``` -{{EmbedLiveSample("at-property-no-inheritance",600,260)}} +{{EmbedLiveSample("",600,260)}} ### Using initial values From 28f63ba32f061d4c28b64083b7dc9971d7b84cf1 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 24 Nov 2023 15:26:18 +0100 Subject: [PATCH 03/20] docs(css): fix flaws in module pages --- files/en-us/web/css/css_cascading_variables/index.md | 2 +- files/en-us/web/css/css_properties_and_values_api/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/css/css_cascading_variables/index.md b/files/en-us/web/css/css_cascading_variables/index.md index b81313bbcea0733..0dcd6cadcde0f10 100644 --- a/files/en-us/web/css/css_cascading_variables/index.md +++ b/files/en-us/web/css/css_cascading_variables/index.md @@ -83,7 +83,7 @@ textarea { ### Functions -- {{cssxref("var()")}} +- {{cssxref("var")}} ## Guides diff --git a/files/en-us/web/css/css_properties_and_values_api/index.md b/files/en-us/web/css/css_properties_and_values_api/index.md index 6a006de28bba62c..de77d77af9689e5 100644 --- a/files/en-us/web/css/css_properties_and_values_api/index.md +++ b/files/en-us/web/css/css_properties_and_values_api/index.md @@ -177,7 +177,7 @@ div { ### Functions -- {{cssxref("var()")}} +- {{cssxref("var")}} ### Interfaces From 29012d36ace26be0bc93b5366d02c0bedccf8e2e Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 24 Nov 2023 15:40:28 +0100 Subject: [PATCH 04/20] docs(css): check-in changes, remove unnecessary styles --- .../web/css/css_cascading_variables/index.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/files/en-us/web/css/css_cascading_variables/index.md b/files/en-us/web/css/css_cascading_variables/index.md index 0dcd6cadcde0f10..86fab428bb92a82 100644 --- a/files/en-us/web/css/css_cascading_variables/index.md +++ b/files/en-us/web/css/css_cascading_variables/index.md @@ -19,7 +19,9 @@ For example, `--dark-grey-text` and `--dark-footer` are easier to understand tha ## Example -The following example shows a +The following example defines a custom property `--main-bg-color` with a value of `cornflowerblue`. +It is scoped to the `.container` class, so children of the matching element inherit its value. +The value is referenced using {{cssxref("var")}} as a property value to give a background color to some elements: ```html
@@ -40,17 +42,10 @@ body { font-family: sans-serif; } -div, -input, -textarea { +div { border: 2px black solid; - padding: 4px; - margin: 4px; -} - -.container { - display: grid; - gap: 10px; + padding: 8px; + margin: 8px; } ``` From 1f5848f3f4a5f2396c81c621efb27a0534ce3994 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 27 Nov 2023 11:51:16 +0100 Subject: [PATCH 05/20] docs(css): changes following reviewer feedback, conform to existing doc conventions for module pages --- .../guide/index.md | 13 -- .../web/css/css_cascading_variables/index.md | 123 ++++++++----- .../css_properties_and_values_api/index.md | 161 +++--------------- 3 files changed, 101 insertions(+), 196 deletions(-) diff --git a/files/en-us/web/api/css_properties_and_values_api/guide/index.md b/files/en-us/web/api/css_properties_and_values_api/guide/index.md index f3c519e440c85bf..e035c91329210dc 100644 --- a/files/en-us/web/api/css_properties_and_values_api/guide/index.md +++ b/files/en-us/web/api/css_properties_and_values_api/guide/index.md @@ -2,11 +2,6 @@ title: Using the CSS properties and values API slug: Web/API/CSS_Properties_and_Values_API/guide page-type: guide -browser-compat: - - css.at-rules.property - - css.properties.custom-property.var - - api.CSSPropertyRule - - api.CSS.registerProperty_static --- {{DefaultAPISidebar("CSS Properties and Values API")}}{{SeeCompatTable}} @@ -110,11 +105,3 @@ While not functionally accurate, a good way to think about the difference betwee There are two gotchas when registering a property. The first is that, once a property is registered, there's no way to update it, and trying to re-register it with [JavaScript](/en-US/docs/Web/JavaScript) will throw an error indicating it's already been defined. Second, unlike standard properties, registered properties aren't validated when they're parsed. Rather, they're validated when they're computed. That means both that invalid values won't appear as invalid when inspecting the element's properties, and that including an invalid property after a valid one won't fall back to the valid property. An invalid property will, however, fall back to its registered default. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/css/css_cascading_variables/index.md b/files/en-us/web/css/css_cascading_variables/index.md index 86fab428bb92a82..cc4e6dd24b9647b 100644 --- a/files/en-us/web/css/css_cascading_variables/index.md +++ b/files/en-us/web/css/css_cascading_variables/index.md @@ -2,100 +2,133 @@ title: CSS custom properties for cascading variables slug: Web/CSS/CSS_cascading_variables page-type: css-module -browser-compat: - - css.properties.custom-property - - css.properties.custom-property.var +spec-urls: https://drafts.csswg.org/css-variables/ --- {{CSSRef}} -The **CSS custom properties for cascading variables** module adds support for cascading variables in for CSS properties and lets you create custom properties to define these variables. +The **CSS custom properties for cascading variables** module adds support for cascading variables in CSS properties and lets you create custom properties to define these variables. Custom properties are defined using [two dashes (`--`)](/en-US/docs/Web/CSS/--*) and are subject to the [cascade](/en-US/docs/Web/CSS/Cascade), so they inherit their value from their parent. The purpose of custom properties is to help manage complex CSS stylesheets by allowing you to define a property's value in one place and reuse that value in multiple declarations across a project. - A benefit of custom properties is improved readability and semantics. For example, `--dark-grey-text` and `--dark-footer` are easier to understand than hexadecimal colors such as `#00ff00`, and the context of their use is much more apparent. -## Example +## Custom properties in action -The following example defines a custom property `--main-bg-color` with a value of `cornflowerblue`. -It is scoped to the `.container` class, so children of the matching element inherit its value. -The value is referenced using {{cssxref("var")}} as a property value to give a background color to some elements: +To see how custom properties can be used, move the input slider left to right. +When the value of the slider changes between 0 and 360, this updates the `--hue` property and color of the boxes inside the grid. +The `--hue` custom property is used in a slightly different way in each box, and changing the value of `--hue` in one place affects multiple different elements where it's referenced. -```html +```html hidden
-
-

One

-
-
-

Two

-
-

Three

-
-
+
--hue
+
--hue + 10
+
--hue + 20
+
--hue + 30
+
--hue + 40
+
--hue + 50
+
--hue + 60
+
--hue + 70
+ +``` + +```js hidden +const hue = document.querySelector("#hue"); + +const updateHue = () => { + document.documentElement.style.setProperty("--hue", hue.value); +}; + +hue.addEventListener("input", updateHue); ``` ```css hidden -body { +.container { + display: grid; font-family: sans-serif; + color: white; + gap: 0.5rem; + grid-template-columns: repeat(4, 1fr); + margin-bottom: 1rem; +} +.container div { + border-radius: 0.5rem; + padding: 1rem; } -div { - border: 2px black solid; - padding: 8px; - margin: 8px; +input { + width: 100%; + margin: 0; } ``` ```css -/* Define --main-bg-color here */ -.container { - --main-bg-color: cornflowerblue; +:root { + --hue: 0; } -/* For each class, set some colors */ -.one { - background-color: var(--main-bg-color); +#color-1 { + background-color: hsl(var(--hue) 50% 50%); +} +#color-2 { + background-color: hsl(calc(var(--hue) + 10) 50% 50%); } -.two { - color: black; - background-color: aquamarine; +#color-3 { + background-color: hsl(calc(var(--hue) + 20) 50% 50%); } -.three { - background-color: var(--main-bg-color); +#color-4 { + background-color: hsl(calc(var(--hue) + 30) 50% 50%); } +/* Continued up to color-8 ... */ ``` -{{EmbedLiveSample("",600,360)}} +```css hidden +#color-5 { + background-color: hsl(calc(var(--hue) + 40) 50% 50%); +} +#color-6 { + background-color: hsl(calc(var(--hue) + 50) 50% 50%); +} +#color-7 { + background-color: hsl(calc(var(--hue) + 60) 50% 50%); +} +#color-8 { + background-color: hsl(calc(var(--hue) + 70) 50% 50%); +} +``` + +{{EmbedLiveSample("",600,160)}} ## Reference ### Properties -- {{cssxref("--*")}} +- {{cssxref("--*")}} syntax for defining custom properties in CSS. ### Functions -- {{cssxref("var")}} +- {{cssxref("var")}} for referencing a custom property's value. ## Guides - [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) + - : Explains how to use custom properties in CSS and JavaScript, with hints on handling undefined and invalid values, fallbacks, and inheritance. -## Specifications +## Related concepts -{{Specifications}} +- The [CSS Properties and Values API](/en-US/docs/Web/CSS/CSS_properties_and_values_API) provides additional interfaces for defining custom properties that allow you to set an initial value fir the property, define data type constraints and provide control over inheritance. + This specification provides: -## Browser compatibility + - [CSS @property](/en-US/docs/Web/CSS/@property) at-rule for defining custom properties in CSS. + - [CSS.registerProperty()](/en-US/docs/Web/API/CSS/registerProperty_static) method for defining custom properties in JavaScript. -{{Compat}} +## Specifications + +{{Specifications}} ## See also - [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade) -- [CSS Properties and Values API](/en-US/docs/Web/CSS/CSS_properties_and_values_API) module - [CSS `env()`](Web/CSS/env) -- [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API) -- [CSS Houdini](/en-US/docs/Web/Guide/Houdini) diff --git a/files/en-us/web/css/css_properties_and_values_api/index.md b/files/en-us/web/css/css_properties_and_values_api/index.md index de77d77af9689e5..047ffd225f5923f 100644 --- a/files/en-us/web/css/css_properties_and_values_api/index.md +++ b/files/en-us/web/css/css_properties_and_values_api/index.md @@ -1,12 +1,8 @@ --- -title: CSS Properties and Values API +title: CSS properties and values API slug: Web/CSS/CSS_properties_and_values_API page-type: css-module -browser-compat: - - css.at-rules.property - - css.properties.custom-property.var - - api.CSSPropertyRule - - api.CSS.registerProperty_static +spec-urls: https://www.w3.org/TR/css-properties-values-api-1/ --- {{CSSRef}} @@ -17,157 +13,49 @@ This API expands on [CSS custom properties for cascading variables](Web/CSS/CSS_ The additional functionality provided by the Properties and Values API is the introduction of control over inheritance, the ability to set initial values, and data type constraints. Authors can define CSS properties using the [`@property`](/en-US/docs/Web/CSS/@property) at-rule in CSS and the {{domxref('CSS/registerProperty_static', 'CSS.registerProperty')}} interface in JavaScript. -## Examples +## Properties and Values API in action -### Registering custom properties in JavaScript - -Registering custom properties is done using {{domxref('CSS/registerProperty_static', 'CSS.registerProperty')}}. -Because inheritance is disabled, the value `cornflowerblue` set in the parent element is not defined in the scope of the `.child` element, and the initial value of `cornflowerblue` is used: +Registered properties have an associated data type that the browser can use in different contexts, which makes them a great choice for animations and transitions. +Using custom properties defined in CSS using the [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*) works more like a string substitution, so a CSS [transition](/en-US/docs/Web/CSS/transition) won't work as expected. +When you hover over the box below, the background color changes over two seconds with proper interpolation between the different colors. ```js -window.CSS.registerProperty({ - name: "--custom-bg-color", +CSS.registerProperty({ + name: "--stop-color", syntax: "", inherits: false, - initialValue: "aquamarine", + initialValue: "cornflowerblue", }); ``` ```css hidden -div { - font-family: sans-serif; - width: 200px; - height: 200px; - margin: 10px; - padding: 10px; - border: 2px black solid; -} - -.child { +.box { + padding: 1rem; width: 80%; - height: 80%; -} -``` - -```css -.parent { - --custom-bg-color: cornflowerblue; - background-color: var(--custom-bg-color); -} - -.child { - background-color: var(--custom-bg-color); -} -``` - -```html -
-
-

Custom property registered in JavaScript

-
-
-``` - -{{EmbedLiveSample("",600,260)}} - -### Using the `@property` at-rule in CSS - -The following example shows a custom property (`--box-color`) defined using the `@property` at-rule. -This custom property represents a color data type and has a default value of `cornflowerblue`. -The `inherits: false;` property ensures that the custom property does not inherit its value from its parent. - -The element with the `.child` class has a style declaration that sets its background to the `--box-color` property value. -The value `green` set in the parent element is not defined in the scope of the `.child` element, and the initial value of `cornflowerblue` is used: - -```css hidden -div { + height: 4rem; font-family: sans-serif; - width: 200px; - height: 200px; - margin: 10px; - padding: 10px; - border: 2px black solid; color: white; -} - -.child { - width: 80%; - height: 80%; + border-radius: 0.5rem; } ``` ```css -@property --box-color { - syntax: ""; - inherits: false; - initial-value: cornflowerblue; +.box { + --stop-color: cornflowerblue; + background: linear-gradient(to right, var(--stop-color), lavenderblush); + transition: --stop-color 2s; } -.parent { - --box-color: green; - background-color: var(--box-color); -} - -.child { - background-color: var(--box-color); +.box:hover { + --stop-color: aquamarine; } ``` -```html -
-
-

@property at-rule example

-
-
+```html hidden +

Linear gradient with transition

``` -{{EmbedLiveSample("",600,260)}} - -### Using initial values - -If a custom property is not defined, the initial value can be used as a fallback. -In the following example, a custom property is defined using the `@property` syntax with `cornflowerblue` as the initial value. -The `.parent` element uses this color as its background color while the property is not defined outside of the at-rule. -The initial value is used instead of the background color inherited from its parent: - -```css hidden -div { - font-family: sans-serif; - width: 200px; - height: 200px; - margin: 10px; - padding: 10px; - border: 2px black solid; - color: white; -} - -.child { - width: 80%; - height: 80%; -} -``` - -```css -@property --box-color { - syntax: ""; - inherits: true; - initial-value: cornflowerblue; -} - -.parent { - background-color: var(--box-color); -} -``` - -```html -
-
-

Undefined property value for --box-color

-
-
-``` - -{{EmbedLiveSample("",600,260)}} +{{EmbedLiveSample("",600,120)}} ## Reference @@ -186,15 +74,12 @@ div { ## Guides - [Using the CSS properties and values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API/guide) + - : Explains how to register custom properties in CSS and JavaScript, with hints on handling undefined and invalid values, fallbacks, and inheritance. ## Specifications {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade) From 322febd872017c21a00f72af64edb948e989915f Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 27 Nov 2023 16:36:31 +0100 Subject: [PATCH 06/20] Apply suggestions from code review Co-authored-by: Estelle Weyl --- files/en-us/web/css/css_cascading_variables/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/en-us/web/css/css_cascading_variables/index.md b/files/en-us/web/css/css_cascading_variables/index.md index cc4e6dd24b9647b..ecc9c902309140a 100644 --- a/files/en-us/web/css/css_cascading_variables/index.md +++ b/files/en-us/web/css/css_cascading_variables/index.md @@ -17,8 +17,6 @@ For example, `--dark-grey-text` and `--dark-footer` are easier to understand tha ## Custom properties in action To see how custom properties can be used, move the input slider left to right. -When the value of the slider changes between 0 and 360, this updates the `--hue` property and color of the boxes inside the grid. -The `--hue` custom property is used in a slightly different way in each box, and changing the value of `--hue` in one place affects multiple different elements where it's referenced. ```html hidden
@@ -64,7 +62,7 @@ input { } ``` -```css +```css hidden :root { --hue: 0; } @@ -101,6 +99,8 @@ input { {{EmbedLiveSample("",600,160)}} +Each color swatch increments the {{cssxref("hue")}} value by 10 degrees, changing the {{cssxref("background-color")}} using the {{cssxref("hsl")}} {{cssxref("<color>")}} function`hsl(var(--hue) 50% 50%);`. When the slider's value changes between 0 and 360, this updates a `--hue` [custom property]((/en-US/docs/Web/CSS/--*) and the color of the boxes inside the grid. + ## Reference ### Properties From 7d11339c1ab46603d443421b562a449f680a5e59 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 27 Nov 2023 17:23:02 +0100 Subject: [PATCH 07/20] docs(css): changes following reviewer feedback, make hidden examples a single block --- .../web/css/css_cascading_variables/index.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/files/en-us/web/css/css_cascading_variables/index.md b/files/en-us/web/css/css_cascading_variables/index.md index ecc9c902309140a..685a1afca3e0b80 100644 --- a/files/en-us/web/css/css_cascading_variables/index.md +++ b/files/en-us/web/css/css_cascading_variables/index.md @@ -9,10 +9,10 @@ spec-urls: https://drafts.csswg.org/css-variables/ The **CSS custom properties for cascading variables** module adds support for cascading variables in CSS properties and lets you create custom properties to define these variables. -Custom properties are defined using [two dashes (`--`)](/en-US/docs/Web/CSS/--*) and are subject to the [cascade](/en-US/docs/Web/CSS/Cascade), so they inherit their value from their parent. -The purpose of custom properties is to help manage complex CSS stylesheets by allowing you to define a property's value in one place and reuse that value in multiple declarations across a project. -A benefit of custom properties is improved readability and semantics. -For example, `--dark-grey-text` and `--dark-footer` are easier to understand than hexadecimal colors such as `#00ff00`, and the context of their use is much more apparent. +When working with CSS, you often end up reusing common project-specific values such as widths that work well with your layout, or a set of colors for your color scheme. +One way of managing repetition in stylesheets is to define a value once and use it many times in other places. +Custom properties let you reuse values and simplify complex or repetitive rules which is easier to read and maintain. +For example, `--dark-grey-text` and `--dark-footer` are easier to understand than hexadecimal colors such as `#00ff00`, and the context of how you use them is more obvious, too. ## Custom properties in action @@ -60,9 +60,7 @@ input { width: 100%; margin: 0; } -``` -```css hidden :root { --hue: 0; } @@ -79,10 +77,6 @@ input { #color-4 { background-color: hsl(calc(var(--hue) + 30) 50% 50%); } -/* Continued up to color-8 ... */ -``` - -```css hidden #color-5 { background-color: hsl(calc(var(--hue) + 40) 50% 50%); } @@ -99,7 +93,7 @@ input { {{EmbedLiveSample("",600,160)}} -Each color swatch increments the {{cssxref("hue")}} value by 10 degrees, changing the {{cssxref("background-color")}} using the {{cssxref("hsl")}} {{cssxref("<color>")}} function`hsl(var(--hue) 50% 50%);`. When the slider's value changes between 0 and 360, this updates a `--hue` [custom property]((/en-US/docs/Web/CSS/--*) and the color of the boxes inside the grid. +Each color swatch increments the {{cssxref("hue")}} value by 10 degrees, changing the {{cssxref("background-color")}} using the {{cssxref("color_value/hsl", "hsl()")}} {{cssxref("<color>")}} function (`hsl(var(--hue) 50% 50%);`). When the slider's value changes between 0 and 360, this updates a `--hue` [custom property](/en-US/docs/Web/CSS/--*) and the color of the boxes inside the grid. ## Reference From 9671942a35dfb62a1b778559fa6430ff958c446d Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 27 Nov 2023 18:29:44 +0100 Subject: [PATCH 08/20] docs(css): changes following reviewer feedback --- files/en-us/web/api/css/index.md | 3 +++ files/en-us/web/css/@property/index.md | 12 +++++++++--- .../web/css/css_cascading_variables/index.md | 9 ++++----- .../css/css_properties_and_values_api/index.md | 18 +++++++++++++++++- 4 files changed, 33 insertions(+), 9 deletions(-) diff --git a/files/en-us/web/api/css/index.md b/files/en-us/web/api/css/index.md index 41d65c8bd7120f7..aca813ce8c0a562 100644 --- a/files/en-us/web/api/css/index.md +++ b/files/en-us/web/api/css/index.md @@ -3,6 +3,9 @@ title: CSS slug: Web/API/CSS page-type: web-api-interface browser-compat: api.CSS +spec-urls: + - https://drafts.csswg.org/cssom/#namespacedef-css + - https://www.w3.org/TR/css-properties-values-api-1/ --- {{APIRef("CSSOM")}} diff --git a/files/en-us/web/css/@property/index.md b/files/en-us/web/css/@property/index.md index 2998f6afffdc488..3f315e81d00a987 100644 --- a/files/en-us/web/css/@property/index.md +++ b/files/en-us/web/css/@property/index.md @@ -30,12 +30,17 @@ The `@property` rule represents a custom property registration directly in a sty - {{cssxref("@property/initial-value","initial-value")}} - : Sets the initial value for the property. -A valid `@property` rule represents a custom property registration, with the property name being the serialization of the in the rule's prelude. - -`@property` rules require a {{cssxref("@property/syntax","syntax")}} and {{cssxref("@property/inherits","inherits")}} descriptor; if either are missing, the entire rule is invalid and must be ignored. The {{cssxref("@property/initial-value","initial-value")}} descriptor is optional only if the syntax is the universal syntax definition, otherwise the descriptor is required; if it's missing, the entire rule is invalid and must be ignored. +`@property` rules require a {{cssxref("@property/syntax","syntax")}} and {{cssxref("@property/inherits","inherits")}} descriptor; if either are missing, the entire rule is invalid and must be ignored. The {{cssxref("@property/initial-value","initial-value")}} descriptor is optional only if the syntax is the universal syntax definition (`*`), otherwise the descriptor is required; if it's missing, the entire rule is invalid and must be ignored. Unknown descriptors are invalid and ignored, but do not invalidate the `@property` rule. +#### Syntax strings + +The `` descriptor can be any one of ``, ``, ``, ``, ``, ``, ``, ``, ``, `