-
Notifications
You must be signed in to change notification settings - Fork 22.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(css): add module page for CSS Properties and Values API (#30503)
* docs(css): add module page for CSS Properties and Values API * link to guides and module pages * docs(css): remove unnecessary string identifier * docs(css): fix flaws in module pages * docs(css): check-in changes, remove unnecessary styles * docs(css): changes following reviewer feedback, conform to existing doc conventions for module pages * Apply suggestions from code review Co-authored-by: Estelle Weyl <estelle@openwebdocs.org> * docs(css): changes following reviewer feedback, make hidden examples a single block * docs(css): changes following reviewer feedback * docs(css): changes following reviewer feedback * Update files/en-us/web/css/css_cascading_variables/index.md Co-authored-by: Estelle Weyl <estelle@openwebdocs.org> * docs(css): changes following reviewer feedback * docs(css): changes following reviewer feedback * Apply suggestions from code review Co-authored-by: Estelle Weyl <estelle@openwebdocs.org> * Fix typos Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * docs(css): Move 'syntax strings' up into syntax DL * docs(css): Improvements following reviewer feedback * Update files/en-us/web/css/css_properties_and_values_api/index.md Co-authored-by: Estelle Weyl <estelle@openwebdocs.org> * Apply suggestions from code review Co-authored-by: Estelle Weyl <estelle@openwebdocs.org> * docs(css): Correct internal xrefs to use locale / root relative * docs(css): Improvements following reviewer feedback --------- Co-authored-by: Estelle Weyl <estelle@openwebdocs.org> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
- Loading branch information
3 people
committed
Dec 18, 2023
1 parent
74cd14d
commit 948ade9
Showing
8 changed files
with
253 additions
and
11 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,20 +1,134 @@ | ||
| --- | ||
| 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/ | ||
| --- | ||
|
|
||
| {{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 CSS properties and lets you create custom properties to define these variables along with the mechanisms to use custom properties as the values for other CSS properties. | ||
|
|
||
| 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 create and define custom variables that can be reused, simplifying complex or repetitive rules and making them easier to read and maintain. | ||
| For example, `--dark-grey-text` and `--dark-background` are easier to understand than hexadecimal colors such as `#323831`, and the context of how you use them is more obvious, too. | ||
|
|
||
| ## Custom properties in action | ||
|
|
||
| To see how custom properties can be used, move the input slider left to right. | ||
|
|
||
| ```html hidden | ||
| <div class="container"> | ||
| <div id="color-1">--hue</div> | ||
| <div id="color-2">--hue + 10</div> | ||
| <div id="color-3">--hue + 20</div> | ||
| <div id="color-4">--hue + 30</div> | ||
| <div id="color-5">--hue + 40</div> | ||
| <div id="color-6">--hue + 50</div> | ||
| <div id="color-7">--hue + 60</div> | ||
| <div id="color-8">--hue + 70</div> | ||
| </div> | ||
| <input type="range" min="0" max="360" value="0" step="0.1" id="hue" /> | ||
| ``` | ||
|
|
||
| ```js hidden | ||
| const hue = document.querySelector("#hue"); | ||
|
|
||
| const updateHue = () => { | ||
| document.documentElement.style.setProperty("--hue", hue.value); | ||
| }; | ||
|
|
||
| hue.addEventListener("input", updateHue); | ||
| ``` | ||
|
|
||
| ```css hidden | ||
| .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; | ||
| } | ||
|
|
||
| input { | ||
| width: 100%; | ||
| margin: 0; | ||
| } | ||
|
|
||
| :root { | ||
| --hue: 0; | ||
| } | ||
|
|
||
| #color-1 { | ||
| background-color: hsl(var(--hue) 50% 50%); | ||
| } | ||
| #color-2 { | ||
| background-color: hsl(calc(var(--hue) + 10) 50% 50%); | ||
| } | ||
| #color-3 { | ||
| background-color: hsl(calc(var(--hue) + 20) 50% 50%); | ||
| } | ||
| #color-4 { | ||
| background-color: hsl(calc(var(--hue) + 30) 50% 50%); | ||
| } | ||
| #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)}} | ||
|
|
||
| In these color swatches, the {{cssxref("background-color")}} is set using the {{cssxref("color_value/hsl", "hsl()")}} {{cssxref("<color>")}} function as `hsl(var(--hue) 50% 50%)`. | ||
| Each color swatch increments the {{cssxref("hue")}} value by 10 degrees like `calc(var(--hue) + 10)`, `calc(var(--hue) + 20)` etc. | ||
| As the slider's value changes from 0 up to 360, the value of the `--hue` [custom property](/en-US/docs/Web/CSS/--*) is updated using {{cssxref("calc")}}, and the background color of each box inside the grid is updated, also. | ||
|
|
||
| ## Reference | ||
|
|
||
| ### Properties | ||
|
|
||
| - {{cssxref("--*")}} | ||
|
|
||
| ### Functions | ||
|
|
||
| - {{cssxref("var")}} | ||
|
|
||
| ## 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. | ||
|
|
||
| - [Invalid custom properties](/en-US/docs/Web/CSS/CSS_syntax/Error_handling#invalid_custom_properties) | ||
| - : Explains how browsers handle property values when a custom property's value is an invalid data type for that property. | ||
|
|
||
| ## Related concepts | ||
|
|
||
| - [CSS Properties and Values API](/en-US/docs/Web/CSS/CSS_properties_and_values_API) module | ||
| - [`@property`](/en-US/docs/Web/CSS/@property) at-rule | ||
| - [`CSS.registerProperty()`](/en-US/docs/Web/API/CSS/registerProperty_static) method | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade) module | ||
| - [CSS `env()`](/en-US/docs/Web/CSS/env) function | ||
| - [CSS `calc()`](/en-US/docs/Web/CSS/calc) function | ||
| - [`getPropertyValue()`](/en-US/docs/Web/API/CSSStyleDeclaration/getPropertyValue) method |
113 changes: 113 additions & 0 deletions
113
files/en-us/web/css/css_properties_and_values_api/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| --- | ||
| title: CSS properties and values API | ||
| slug: Web/CSS/CSS_properties_and_values_API | ||
| page-type: css-module | ||
| spec-urls: https://www.w3.org/TR/css-properties-values-api-1/ | ||
| --- | ||
|
|
||
| {{CSSRef}} | ||
|
|
||
| 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](/en-US/docs/Web/CSS/CSS_cascading_variables) module, which allows authors to define custom properties in CSS using [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*). | ||
| The CSS properties and values API is part of the [CSS Houdini](/en-US/docs/Web/CSS/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](/en-US/docs/Web/CSS/CSS_cascading_variables) module. | ||
| The CSS properties and values API expands on that module, enabling adding metadata to custom properties using CSS with the [`@property`](/en-US/docs/Web/CSS/@property) at-rule or, alternatively, using JavaScript's {{domxref('CSS/registerProperty_static', '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 (`--`)](/en-US/docs/Web/CSS/--*) 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. | ||
|
|
||
| ```js hidden | ||
| CSS.registerProperty({ | ||
| name: "--stop-color", | ||
| syntax: "<color>", | ||
| inherits: false, | ||
| initialValue: "cornflowerblue", | ||
| }); | ||
| ``` | ||
|
|
||
| ```css hidden | ||
| .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; | ||
| } | ||
| ``` | ||
|
|
||
| ```html hidden | ||
| <div class="box"><p>Linear gradient with transition</p></div> | ||
| ``` | ||
|
|
||
| {{EmbedLiveSample("",600,120)}} | ||
|
|
||
| The box has a [backround](/en-US/docs/Web/CSS/background) consisting of a [linear gradient](/en-US/docs/Web/CSS/gradient/linear-gradient) from `--stop-color` (the custom property) to [`lavenderblush`](/en-US/docs/Web/CSS/named-color). | ||
| The value of `--stop-color` is set to `cornflowerblue` at first, but when you hover over the box, `--stop-color` [transitions](/en-US/docs/Web/CSS/transition) to `aquamarine` over two seconds (`linear-gradient(to right, aquamarine, lavenderblush)`). | ||
|
|
||
| ## Reference | ||
|
|
||
| ### At-rules | ||
|
|
||
| - {{cssxref("@property")}} | ||
| - [syntax](/en-US/docs/Web/CSS/@property#descriptors) descriptor | ||
| - [`+` and `#`](/en-US/docs/Web/CSS/@property#descriptors) multipliers | ||
| - [`|`](/en-US/docs/Web/CSS/@property#descriptors) combinator | ||
| - [inherits](/en-US/docs/Web/CSS/@property#descriptors) descriptor | ||
| - [initial-value](/en-US/docs/Web/CSS/@property#descriptors) descriptor | ||
|
|
||
| ### Interfaces and APIs | ||
|
|
||
| - {{domxref('CSSPropertyRule')}} | ||
| - {{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) | ||
|
|
||
| - : Explains how to register custom properties in CSS and JavaScript, with hints on handling undefined and invalid values, fallbacks, and inheritance. | ||
|
|
||
| - [CSS Houdini](/en-US/docs/Web/Guide/Houdini) | ||
| - : Explains what CSS Houdini is and its advantages, along with a list of available APIs and their statuses. | ||
|
|
||
| ## Related concepts | ||
|
|
||
| - {{cssxref("var")}} | ||
| - [CSSRule](/en-US/docs/Web/API/CSSRule) | ||
| - [CSSStyleValue](/en-US/docs/Web/API/CSSStyleValue) | ||
| - [CSS scoping](/en-US/docs/Web/CSS/CSS_scoping) | ||
| - [Using shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) | ||
| - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) | ||
| - [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API) | ||
| - [Worklet](/en-US/docs/Web/API/Worklet) | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade) | ||
| - [CSS scoping](/en-US/docs/Web/CSS/CSS_scoping) module | ||
| - [Using shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) | ||
| - [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API) module | ||
| - [Worklet](/en-US/docs/Web/API/Worklet) interface | ||
| - [CSS `env()`](/en-US/docs/Web/CSS/env) | ||
| - [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters