From af6df16285c7bd98d35a8b3f8614df728ef8283a Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Thu, 13 Feb 2025 19:49:06 +0000 Subject: [PATCH 01/12] stub in new VDOM props page w/link from sidebar --- content/en/guide/v10/vdom-reference.md | 27 ++++++++++++++++++++++++++ src/config.json | 6 ++++++ 2 files changed, 33 insertions(+) create mode 100644 content/en/guide/v10/vdom-reference.md diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md new file mode 100644 index 000000000..2062e4402 --- /dev/null +++ b/content/en/guide/v10/vdom-reference.md @@ -0,0 +1,27 @@ +--- +name: VDOM Properties Reference +description: 'Learn more about how Preact uses special properties of your VDOM components' +--- + +# VDOM Properties Reference + +This page describes how Preact applies rendered component properties to the DOM. + +--- + +
+ +--- + +## ref + +## style + +## children + +## dangerouslySetInnerHTML + +## on* + +### on*Capture + diff --git a/src/config.json b/src/config.json index 6820dcf25..499d18dec 100644 --- a/src/config.json +++ b/src/config.json @@ -443,6 +443,12 @@ "ru": "Справочник по API" } }, + { + "path": "/vdom-reference", + "name": { + "en": "VDOM Properties Reference" + } + }, { "path": "/web-components", "name": { From ed853aa8d001a1fe0d69ada97c0abff647815947 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Thu, 13 Feb 2025 21:27:09 +0000 Subject: [PATCH 02/12] rough first pass re. the `ref` property --- content/en/guide/v10/vdom-reference.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 2062e4402..8b3fbc8cd 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -15,8 +15,17 @@ This page describes how Preact applies rendered component properties to the DOM. ## ref +See the [References documentation](/guide/v10/refs#createref) for an introduction to this property. + +The value can be a function, in which case it will be called with a reference to the element (or component) once it is mounted. If the function returns a cleanup function, then it will be called when unmounting, otherwise the function will be called again with `null`. + +The value can also be a non-callable object, in which case Preact will assign the element (or null) to that object's `.current` property. + +Note that this is a particularly special property in that this it is [not currently](https://github.com/preactjs/preact/pull/4658) passed through to custom components. See [forwardRef](/guide/v10/switching-to-preact#forwardref) for a workaround. + ## style + ## children ## dangerouslySetInnerHTML From ca7af7c03a4e7ea51f2dd3cf99c4bf099fabb0d4 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Thu, 13 Feb 2025 22:15:17 +0000 Subject: [PATCH 03/12] add in rough notes re. `key` property --- content/en/guide/v10/vdom-reference.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 8b3fbc8cd..56b69b1dc 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -13,6 +13,14 @@ This page describes how Preact applies rendered component properties to the DOM. --- +## key + +The value of this property provides an identity for the VDOM node when diffing against a previous render. +See the [Keys tutorial](/tutorial/08-keys/) for background. + +Note that this is a particularly special property in that it is intercepted by Preact and *not* passed along to any custom component. + + ## ref See the [References documentation](/guide/v10/refs#createref) for an introduction to this property. From 7847a68da58c4619f12e0b8659f7b37ac99627ea Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Thu, 13 Feb 2025 23:28:13 +0000 Subject: [PATCH 04/12] first pass on style and class props --- content/en/guide/v10/vdom-reference.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 56b69b1dc..e17ec84dd 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -29,10 +29,26 @@ The value can be a function, in which case it will be called with a reference to The value can also be a non-callable object, in which case Preact will assign the element (or null) to that object's `.current` property. -Note that this is a particularly special property in that this it is [not currently](https://github.com/preactjs/preact/pull/4658) passed through to custom components. See [forwardRef](/guide/v10/switching-to-preact#forwardref) for a workaround. +Note that this is, like `key`, also a particularly special property in that this it is [not currently](https://github.com/preactjs/preact/pull/4658) passed through to custom components. See [forwardRef](/guide/v10/switching-to-preact#forwardref) for a workaround. + ## style +This value can be a string containing inline CSS as it would appear in plain HTML. Note, however, that any string will be applied via `dom.style.cssText = value` which parses the CSS and will result in an empty attribute in case of any syntax error rather than the content being applied verbatim. + +This value can also be an object, in which case each of its individual entries are applied as [individual CSS properties](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration/setProperty) on the element (at default [priority](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity#the_!important_exception)). Each key of your object may use the either the dashed style (e.g. `{"text-decoration-color": "blue"}`) or, for [CSS properties the browser is aware of](https://www.w3.org/TR/cssom-1/#dom-cssstyledeclaration-camel-cased-attribute), a camelCased style may be used as well (e.g. `{textDecorationColor: "blue"}`). + +### Numeric values + +Numeric values of style objects entries will have a "px" suffix **automatically appended** unless the CSS property name is either a custom one (e.g. `--my-var`) or is [known to be "non-dimensional"](https://github.com/preactjs/preact/blob/face9247724db0a74b764316c4486f384b89cfed/src/constants.js#L20-L21). This is for compatibility with React, but will likely be [removed from Preact core](https://github.com/preactjs/preact/issues/2621) in a future version. + + +## class / className + +Preact core supports both `class` and `className` for setting the respective attribute/property. See [Preact's philosophy around raw attribute/property usage](/guide/v10/differences-to-react#raw-html-attributeproperty-names) for more discussion. + +Note that if values for *both* are provided on your VDOM node, note that `class` will normally be set as an attribute and `className` will be set as a property — but whichever one ends up being iterated last during the DOM diffing tends to clobber the other regardless. + ## children From b6243c744676ad50f0527aeda52ed00c8e66fc61 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Thu, 13 Feb 2025 23:48:28 +0000 Subject: [PATCH 05/12] go with some gory details for a bit --- content/en/guide/v10/vdom-reference.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index e17ec84dd..03eb35344 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -47,7 +47,7 @@ Numeric values of style objects entries will have a "px" suffix **automatically Preact core supports both `class` and `className` for setting the respective attribute/property. See [Preact's philosophy around raw attribute/property usage](/guide/v10/differences-to-react#raw-html-attributeproperty-names) for more discussion. -Note that if values for *both* are provided on your VDOM node, note that `class` will normally be set as an attribute and `className` will be set as a property — but whichever one ends up being iterated last during the DOM diffing tends to clobber the other regardless. +Iff values for *both* are provided on your VDOM node, note that `class` will the be set as an attribute (under normal circumstances) and `className` will be set as a property — but whichever one ends up being iterated last during the DOM diffing tends to clobber the other regardless. ## children @@ -58,3 +58,16 @@ Note that if values for *both* are provided on your VDOM node, note that `class` ### on*Capture + +## Other special properties + +Preact core includes many other special property fixups including for: + +* certain form/display elements +* certain event names and HTML attributes +* various idiosyncracies of the [SVG DOM](https://www.w3.org/TR/SVG11/svgdom.html) +* … etc. + +The list above is not intended to be comprehensive. There are many nuances both for specific bugfixes and that simply fall out of the how the internals have gotten implemented. (For example of one such edge case, currently if you assign your own property value to a raw DOM node object in an uncontrolled way e.g. `spanRef.current["data-myvar"] = null` it may then interfere w/Preact's fallback attribute setting of ``.) + +Your best guide for advanced details would be to refer to the [`diff/props.js` source code](https://github.com/preactjs/preact/blob/main/src/diff/props.js), as well as the overarching diffing algorithm itself ([e.g.](https://github.com/preactjs/preact/blob/face9247724db0a74b764316c4486f384b89cfed/src/diff/index.js#L554-L576)) corresponding to the specific version of Preact you are using. From 83a2abe886d1a5302bc63f8d99ae7c911069ada7 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Fri, 14 Feb 2025 00:25:40 +0000 Subject: [PATCH 06/12] some event handling notes --- content/en/guide/v10/vdom-reference.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 03eb35344..55235b4aa 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -52,12 +52,31 @@ Iff values for *both* are provided on your VDOM node, note that `class` will the ## children + +The value of the property itself is under the control of Preact, e.g. in the following example despite passing some other value for the prop, `MyComponent` would not receive a `children` entry in its props because there are no actual child vnodes: + +```jsx + + +``` + ## dangerouslySetInnerHTML +For regular DOM nodes, this provides a way to take over the rendered contents. Like [React's version](https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html), it expects an object with an `__html` property whose value is to be set as the [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) of the element. + +For functional/class-based components this is treated just as any other arbitrary property. The value would be available to the component's implementation but does not directly influence/override its rendered output. (TBD: but does [diff-skipping](https://preactjs.com/guide/v10/upgrade-guide/#dangerouslysetinnerhtml-will-skip-diffing-of-children) still apply?) + ## on* +For property names beginning with "on…" Preact registers an event handler. See the [Events tutorial](/tutorial/02-events/) for additional explanation. + +Note that while Preact core does do a bit of fix up here and there (see [Other special properties](#other-special-properties) below…) it generally follows the underlying browser DOM event naming/behavior more plainly and directly when you are not using `preact/compat`. + + ### on*Capture +If your event property name ends with "…Capture" (but *not* ["…PointerCapture"](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events#pointer_capture) ;-) then Preact will register your event handler during the capture (rather than bubbling) phase. + ## Other special properties From 5187be087c0e161abd5a35485f44bbeaf4310520 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Fri, 14 Feb 2025 00:26:37 +0000 Subject: [PATCH 07/12] few tweaks to UTSL section --- content/en/guide/v10/vdom-reference.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 55235b4aa..69db4eb46 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -87,6 +87,8 @@ Preact core includes many other special property fixups including for: * various idiosyncracies of the [SVG DOM](https://www.w3.org/TR/SVG11/svgdom.html) * … etc. -The list above is not intended to be comprehensive. There are many nuances both for specific bugfixes and that simply fall out of the how the internals have gotten implemented. (For example of one such edge case, currently if you assign your own property value to a raw DOM node object in an uncontrolled way e.g. `spanRef.current["data-myvar"] = null` it may then interfere w/Preact's fallback attribute setting of ``.) +The list above is not intended to be comprehensive. + +There are many nuances both for specific bugfixes/workarounds/compatibility concessions, and other nuances that simply fall out of the how the internals have gotten implemented. (For example of one such edge case, currently if you assign your own property value to a raw DOM node object in an uncontrolled way e.g. `spanRef.current["data-myvar"] = null` it may then interfere w/Preact's fallback attribute setting of ``.) Your best guide for advanced details would be to refer to the [`diff/props.js` source code](https://github.com/preactjs/preact/blob/main/src/diff/props.js), as well as the overarching diffing algorithm itself ([e.g.](https://github.com/preactjs/preact/blob/face9247724db0a74b764316c4486f384b89cfed/src/diff/index.js#L554-L576)) corresponding to the specific version of Preact you are using. From 3d1f3d3267531b3a5780edaf6793a2cbfe969181 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Fri, 14 Feb 2025 13:21:41 -0800 Subject: [PATCH 08/12] Update content/en/guide/v10/vdom-reference.md Co-authored-by: Ryan Christian <33403762+rschristian@users.noreply.github.com> --- content/en/guide/v10/vdom-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 69db4eb46..6a25ca936 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -75,7 +75,7 @@ Note that while Preact core does do a bit of fix up here and there (see [Other s ### on*Capture -If your event property name ends with "…Capture" (but *not* ["…PointerCapture"](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events#pointer_capture) ;-) then Preact will register your event handler during the capture (rather than bubbling) phase. +If your event property name ends with "…Capture" then Preact will register your event handler during the capture (rather than bubbling) phase. ## Other special properties From cf5248a78cf587b31b1dd386bef787df9ac6bebe Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Fri, 14 Feb 2025 13:21:53 -0800 Subject: [PATCH 09/12] Update content/en/guide/v10/vdom-reference.md Co-authored-by: Ryan Christian <33403762+rschristian@users.noreply.github.com> --- content/en/guide/v10/vdom-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 6a25ca936..a9f9c850f 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -40,7 +40,7 @@ This value can also be an object, in which case each of its individual entries a ### Numeric values -Numeric values of style objects entries will have a "px" suffix **automatically appended** unless the CSS property name is either a custom one (e.g. `--my-var`) or is [known to be "non-dimensional"](https://github.com/preactjs/preact/blob/face9247724db0a74b764316c4486f384b89cfed/src/constants.js#L20-L21). This is for compatibility with React, but will likely be [removed from Preact core](https://github.com/preactjs/preact/issues/2621) in a future version. +Numeric values of style objects entries will have a "px" suffix **automatically appended** unless the CSS property name is either a custom one (e.g. `--my-var`) or is [known to be "non-dimensional"](https://github.com/preactjs/preact/blob/face9247724db0a74b764316c4486f384b89cfed/src/constants.js#L20-L21). This is for compatibility with React, but will likely be [moved into compat](https://github.com/preactjs/preact/issues/2621) in a future version. ## class / className From c15f280fce6800ca472ad22c9dd81d093dc8b9ae Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Fri, 14 Feb 2025 13:22:52 -0800 Subject: [PATCH 10/12] Update content/en/guide/v10/vdom-reference.md Co-authored-by: Ryan Christian <33403762+rschristian@users.noreply.github.com> --- content/en/guide/v10/vdom-reference.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index a9f9c850f..50a786e91 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -47,7 +47,6 @@ Numeric values of style objects entries will have a "px" suffix **automatically Preact core supports both `class` and `className` for setting the respective attribute/property. See [Preact's philosophy around raw attribute/property usage](/guide/v10/differences-to-react#raw-html-attributeproperty-names) for more discussion. -Iff values for *both* are provided on your VDOM node, note that `class` will the be set as an attribute (under normal circumstances) and `className` will be set as a property — but whichever one ends up being iterated last during the DOM diffing tends to clobber the other regardless. ## children From e365a2a7b2062485623d7ff8b9ab3491a7882fa7 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Fri, 14 Feb 2025 21:25:07 +0000 Subject: [PATCH 11/12] drop a few more obscure details re. class/className handling re. https://github.com/preactjs/preact-www/pull/1235#discussion_r1956731924 --- content/en/guide/v10/vdom-reference.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index 50a786e91..f9c8f1748 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -88,6 +88,5 @@ Preact core includes many other special property fixups including for: The list above is not intended to be comprehensive. -There are many nuances both for specific bugfixes/workarounds/compatibility concessions, and other nuances that simply fall out of the how the internals have gotten implemented. (For example of one such edge case, currently if you assign your own property value to a raw DOM node object in an uncontrolled way e.g. `spanRef.current["data-myvar"] = null` it may then interfere w/Preact's fallback attribute setting of ``.) - +There are many nuances both for specific bugfixes/workarounds/compatibility concessions, and other nuances that simply fall out of the how the internals have gotten implemented. Your best guide for advanced details would be to refer to the [`diff/props.js` source code](https://github.com/preactjs/preact/blob/main/src/diff/props.js), as well as the overarching diffing algorithm itself ([e.g.](https://github.com/preactjs/preact/blob/face9247724db0a74b764316c4486f384b89cfed/src/diff/index.js#L554-L576)) corresponding to the specific version of Preact you are using. From 4c42736f1917bae763fbe36962194d837aef8e13 Mon Sep 17 00:00:00 2001 From: Nathan Vander Wilt Date: Fri, 14 Feb 2025 21:33:17 +0000 Subject: [PATCH 12/12] add __html example re. https://github.com/preactjs/preact-www/pull/1235#discussion_r1955646915 --- content/en/guide/v10/vdom-reference.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/en/guide/v10/vdom-reference.md b/content/en/guide/v10/vdom-reference.md index f9c8f1748..68d60e953 100644 --- a/content/en/guide/v10/vdom-reference.md +++ b/content/en/guide/v10/vdom-reference.md @@ -61,7 +61,11 @@ The value of the property itself is under the control of Preact, e.g. in the fol ## dangerouslySetInnerHTML -For regular DOM nodes, this provides a way to take over the rendered contents. Like [React's version](https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html), it expects an object with an `__html` property whose value is to be set as the [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) of the element. +For regular DOM nodes, this provides a way to take over the rendered contents. Like [React's version](https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html), it expects an object with an `__html` property whose value is to be set as the [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) of the element: + +```jsx +
Hello World!' }} /> +``` For functional/class-based components this is treated just as any other arbitrary property. The value would be available to the component's implementation but does not directly influence/override its rendered output. (TBD: but does [diff-skipping](https://preactjs.com/guide/v10/upgrade-guide/#dangerouslysetinnerhtml-will-skip-diffing-of-children) still apply?)