New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC: Plan for custom element attributes/properties in React 19 #11347
Comments
Apologies for the long read, but I wanted to make sure I was thoroughly exploring each option. I don't want to bias things too much with my own opinion, but if I were in a position to choose, I think I'd go with option 3. Option 3 is backwards compatible, declarative, and explicit. There’s no need to maintain a fallback heuristic, and other libraries already provide similar sigils/modifiers. |
Apologies for the long read, but I wanted to make sure I was thoroughly exploring each option. I don't want to bias things too much with my own opinion, but if I were in a position to choose, I think I'd go with option 3.
Option 3 is backwards compatible, declarative, and explicit. There’s no need to maintain a fallback heuristic, and other libraries already provide similar sigils/modifiers.
|
I'm between option 2 and option 3, I think that React has handled behavior and API changes very well in the past. Introducting warnings and links to docs might serve well to help developers understand what's happening under the hood. Option 3 looks attractive because of its declarative nature, while reading JSX code new coming developers will know immediately what React will do when rendering the element. |
Comments on option 2
Do consumers of a custom element need to understand this distinction? Or is that only important to the author of the custom element? It seems like the author of the element will need to handle attributes for anything used in HTML (since that is the only way data gets passed from HTML usage) and properties if they want to support complex values or property get/set from DOM. It is even possible an author could have something initially implemented as an attribute and then later add a property with the same name to support more flexible data types and still back the property with a value stored in the attributes. Naming collisions with future HTMLElement attributes and properties seems like a weakness in the Web Components standards in general since that can lead to errors regardless of the binding approach.
It seems confusing to bind differently based on the value. If the author of the element has not specified a property getter/setter to handle the value then setting the property would cause the element to behave like the value was never specified which might be harder to debug. Comments on option 3Another potential con with option 3 is that it requires the consumer of the custom element to know whether the element has implemented something as a property or as an attribute. If you are using a mix of React components and custom elements it could be confusing to set React props using one syntax and custom element properties using a different syntax. |
I doubt it's actually a huge issue because, as you pointed out, the element author should define an attribute and property for the underlying value and accept data from both. I would also add that they should keep the attribute and property in sync (so setting one sets the other).
I agree but I'm not sure if this is something React needs to try to work around in their library. It feels like a problem that needs to be solved as part of the custom elements spec. I can see if we can discuss it as part of the upcoming TPAC standards meeting. I should add, for properties this isn't as bad because the element-defined property will shadow the future property added to HTMLElement. So if you were passing data to a custom element as a js property, it would continue to work. The main issue seems to be around attributes since they are global.
In the case where a custom element is lazy loaded and "upgraded", it will initially have undefined properties. This addresses that use case by making sure those elements still receive their data and they can use it post-upgrade. It's true that if the author doesn't define a getter/setter for a value this would not be very useful. But it's also not useful to have an
I think you're essentially in the same boat today because there's nothing that forces a custom element author to define an attribute instead of a property. So I could have an element with a properties only API that would not receive any data from React's current system and I would need to know to use Because custom elements are meant as a primitive, there's nothing that enforces creating corresponding attributes and properties. But we're trying very hard to encourage doing so as a best practice, and all of the libraries that I know of today create backing properties for their attributes. [edit] As you stated in your earlier point:
Because you never know how a user will try to pass data to your element, you end up needing to have attribute-property correspondence anyway. I imagine if option 3 shipped that most folks would just bind everything using the |
That's not something React should worry as Rob said in my opinion, it's the custom element author's responsability to inform the user how the element works. And it's actually the way that we need to do it today, for example think about the
render() {
return (
<div className="video--wrapper">
<video muted={ this.state.muted } />
</div>
);
} For the current time you need to create a render() {
return (
<div className="video--wrapper">
<video ref={ el => this.video = el } muted={ this.state.muted } />
</div>
);
} Then create an event handler, an instance method and manually set the property to the DOM element. onCurrenTimeChange(e) {
this.video.currentTime = e.value;
} If you think about it it kinda breaks the declarative model React itself imposes with its API and JSX abstract layer since the render() {
return (
<div className="video--wrapper">
<video muted={ this.state.muted } @currentTime={ this.state.currentTime } />
</div>
);
} My point is that whether you are relying on native or custom elements, you still need to know your way around them based on documentation, the difference that in the second case it should come from the custom element's author. @cjorasch my two cents :) |
If we were designing this from scratch, without needing to consider backwards compatibility, I think option 1 would be the most idiomatic per React’s "JavaScript-centric API to the DOM". With regard to server-side rendering, could that problem be solved by providing an API for application code to inform React on how to map custom element properties to attributes? Similar to the maps that React already maintains for platform-defined attributes? This API would only need to be invoked once per custom element name (not for each instance of it), and only for properties that don't follow a straight 1:1 correspondence with their attribute, which should hopefully be relatively rare. If we're concerned about this being too much of a breaking change though, then I think option 3 is pretty appealing as well. If the sigil signifies a property, I would suggest ".", since that's already JavaScript's property accessor. However, I think it's unfortunate to make every instance of where a custom element is used in an application be responsible for knowing when to use an attribute vs. when to use a property. What I prefer about option 1 is that even if a property to attribute map is needed, that mapping code can be isolated from all the JSX usages. |
Maybe I don't understand the upgrade process. Elements would typically have properties defined as getters/setters in the class prototype. Checking |
Upgrading is the process by which the custom element receives its class. Prior to that, it's not an instance of that class, so the property getters/setters aren't available. |
just checked and it also has a corresponding property though it doesn't seem to be documented on MDN :P
Yeah occasionally you'll encounter properties-only APIs on modern HTML elements.
Yep there's unfortunately no one-size-fits-all attributes/properties rule. But I think generally speaking you can lean heavily on properties and provide syntax so developers can use attributes in special cases. |
@robdodson yeap, I knew about the muted property too We will have to rely on documentation on both native and custom elements, so it's something I wouldn't mind for this decision. While writing the last code snippet I kinda liked the property binding though |
I think this is already the case today though. Since the major custom element libraries (polymer, skate, possibly others?) automatically create backing properties for all exposed attributes, developers could just use the sigil for every property on a custom element. It would probably be a rare occurrence for them to need to switch to using an attribute. RE: upgrade. As @effulgentsia mentioned, it's possible to have a custom element on the page but load its definition at a later time. <app-router>
<my-view1></my-view1>
<my-view2></my-view2>
</app-router> In the above example, we won't load the definition for It's entirely possible to set a property on the element before it has upgraded, and once the definition is loaded the element can grab that data during one of its lifecycle callbacks. |
If developers started doing that, then how would that differentiate using a property because you "can" from using a property because you "must"? And isn't that a differentiation that's needed for server-side rendering? |
Sorry, maybe I phrased that wrong. I meant that developers would likely use the sigil because it would give the most consistent result. You can use it to pass primitive data or rich data like objects and arrays and it'll always work. I think working with properties at runtime is generally preferred to working with attributes since attributes tend to be used more for initial configuration.
It might be the case that on the server the sigil would fallback to setting an attribute. |
I don't think that would work if the reason for the sigil is that it's a property that doesn't exist as an attribute, such as video's currentTime.
I think this differentiation is important, because there's entirely different reasons for choosing to use an attribute or property as an optimization (e.g., SSR preferring attributes vs. client-side rendering preferring properties) vs. something that exists either as only an attribute or only a property.
To be more specific, I'm suggesting something like this:
Examples:
For something that can only be a property (where For something that can only be an attribute (where For something that can be both, React could choose whatever strategy is most optimal. Perhaps that means always setting as a property on client-side, but as an attribute server-side. Perhaps it means setting as an attribute when initially creating the element, but setting as a property when later patching from the vdom. Perhaps it means only setting as an attribute when the value is a primitive type. Ideally, React should be able to change the strategy whenever it wants to as an internal implementation detail. When React encounters a prop for which
But in any case, by keeping this a separate API, the JSX and |
Sorry for the excessive comments, but I thought of another benefit to my proposal above that I'd like to share: Those I think the possibility of such centralization is preferable to a solution that requires every user of the custom element to always have to be explicit with a sigil. |
Option 3 would be my preferred but that's a huge breaking change... What about the inverse? Attributes have a prefix not props? |
Why would it be a breaking change? The current behavior of attributes being the default would remain. The sigil would be opt-in and developers would use it to replace the spots in their code where they currently use a
Can you clarify what you meant by this? |
FYI for anyone following the discussion, I've updated the RFC with a 5th option suggested by members of the React team. |
Option 5 seems safest for us. It lets us add the feature without having to make a decision about “implicit” API right now since the ecosystem is still in the “figuring it out” phase. We can always revisit it in a few years.
My impression is that custom element users in React will eventually want to wrap some custom elements into React components anyway for app-specific behavior/customizations. It is a nicer migration strategy for this case if everything already is a React component, e.g. import XButton from './XButton'; and that happens to be generated by export default ReactDOM.createCustomElementType(...) This lets them replace a React component with a custom component that uses (or even doesn’t use) custom elements at any point in time. So, if people are going to create React components at interop points, we might as well provide a powerful helper to do so. It is also likely that people will share those configs for custom elements they use. And eventually, if we see the ecosystem stabilize, we can adopt a config-less approach. I think the next step here would be to write a detailed proposal for how the config should look like to satisfy all common use cases. It should be compelling enough for custom element + React users, since if it doesn't answer common use cases (like event handling) we're going to end up in the limbo where the feature doesn't provide enough benefit to offset the verbosity. |
Building from my earlier comment, how about:
The logic would then be, for each React prop on an XFoo instance:
I'd like to suggest that the config only be necessary for outlier props. For any prop on the XFoo instance that wasn't included in the config, default it to:
|
Alternatively, maybe it makes sense to keep events in a separate namespace, in which case, remove everything having to do with
|
@gaearon @effulgentsia what do y'all think of a combination of option 1 and option 5? Option 1 would make it easier for the casual user of a custom element to pass rich data. I'm imagining the scenario where I'm building an app and I just want to use a couple of custom elements. I already know how they work and I'm not so invested that I want to write a config for them. Option 5 would be for folks who want to use something like paper-input all over their app and would really like to expose its entire API to everyone on their team. |
For SSR of option 1 the heuristic could be always use an attribute if rendering on the server. A camelCase property gets converted to a dash-case attribute. That seems to be a pretty common pattern across web component libraries. |
I like the idea of an option1 + option5 combination a lot. Meaning that for most custom elements:
would work as expected: prop1 set as a property client-side and as a (dash-cased) attribute server-side. And people could switch to option5 for anything for which the above doesn't suit them. It would be a breaking change though from the way React 16 works. For anyone who experiences that breakage (e.g., they were using a custom element with attributes that aren't backed by properties), they could switch to option5, but it's still a break. I leave it to the React team to decide if that's acceptable. |
Ah, this is what I get for reading this quickly on the train @robdodson Option 5 seems reasonable and straightforward. I like where @effulgentsia is heading. Is there a reason it couldn't be:
Or is supporting multiple types on a single prop valuable? I'd be hesitant with this flow though @effulgentsia:
I don't think I'd want a function prop to default to an event, and is assigning both propertyName and attributeName sensible? When would you want both supported to mimic the question above? |
Quoting from the issue summary's Option 1 pros:
So that's the reason why assigning both propertyName and attributeName is sensible: because it reflects what is actually the case for elements that follow best practice. And by making React aware of that, it allows React to decide which to use based on situation: such as using properties for client-side rendering and attributes for server-side rendering. For custom elements that don't follow best practice and have some attributes without corresponding properties and/or some properties without corresponding attributes, React would need to be aware of that, so that attribute-less-properties aren't rendered during SSR and property-less-attributes can be set with setAttribute() during client-side rendering. With your proposal, that could potentially be done by bit-combining flags, such as:
However, that wouldn't provide a way to express that the attribute name is different from the property name (e.g., camelCase to dash-case). Nor would it provide a way to express how to serialize a rich object to an attribute during SSR (the current behavior of "[object Object]" isn't useful).
Yeah, I think I agree with that as well, hence the follow-up comment. Thanks for validating my hesitance with that! |
I'm willing to try, follow up of conversation with @claviska's shoelace as well as new things in React18. I'm new to this game and don't know the exact reference I should add in the package.json |
@BrunoWinck check out the sandbox I posted above for testing this with Shoelace. You can look at the |
npm install react@experimental react-dom@experimental --save |
With the recent announcement of React 18 and no mention of Web Components in the post is it safe to assume that this is not going to make it into React 18? If not, is there an updated estimate to when this may become available? |
React 18 has essentially no immediate breaking changes. Only minor semantics and new APIs and warnings. It needs a bit more flushing out but the idea is to do a separate major bump that includes this and other backed up DOM binding related changes in that one. All at once so that the upgrade path becomes focused on only breaking changes at the DOM API binding level. It's just better not to couple them. That major bump doesn't have to take very long though. Personally, I'd like to see us removing the synthetic event system at the same time since that simplifies how these bindings work so that they're not separate from other DOM elements. That's a bigger changes that would push it out a little longer. I think that's the big question to resolve in terms of sequencing if we do those are two releases or one. |
Just tested the experimental React branch with web components library I do for my cooperate. Everything is working fine in the experimental React branch. Good job! Too bad that we won't see this change in React 18. |
React maintainers: since there have been some recent comments here about whether or not this will be in React 18, I think it would be helpful if you change this issue's title to explicitly say React 19 or not include a version number. In the meantime, here's a link to #11347 (comment), which might be a helpful comment for people who otherwise don't see it anymore due to GitHub by default hiding comments that aren't either the first few or the last few. |
Since GitHub doesn't send notifications for issue title updates: this feature was postponed till React 19 and is not included in the React 18 RFC (https://github.com/reactjs/rfcs/blob/react-18/text/0000-react-18.md). For more information, see reactjs/rfcs#212 (comment) |
Would love to see some tickets or early/draft rfc's opened for some of these! Removing synthetic events would be super interesting! |
If I want to embed web-component in vanilajs ... |
Nice,thank you! ——weihong
|
@sebmarkbage @gaearon Any updates on when this might be released in the main build of react instead of the experimental build? Is this still expected to be in the v19.0.0 release? |
Wow, can't believe this issue is open since 2017. Remember 2017, seems like a lifetime ago. I still had hair and corona was just a beer. |
At this point I am not sure what to expect anymore. The feature has been delayed a couple of times. Probably all for good reason, but still a damning chain of decisions in spite of web and DOM compatibility. Many libraries now ship shims just for React, as it is the only framework that is lacking support. You are probably better of using these shims than wait for the React core team to ship this after 5 years and counting. |
What can we do as a community of people who haven't participated in this PR yet do to help? Do we need to rally and test? Come up with more test cases? Build demo proof of concept repos? Contribute code? Help clarify Synthetic Events? Find ways to limit scope? This is one of the few opportunities to make a meaningful push forward on web standards adoption where it feels like React is the last hold out, I'm sure there's enough willing hands to help if we knew what was needed. |
If you're interested in shaping the new behavior or making sure that it works as you expect before it gets fully released, then please test it out with react@experimental. When the React team ships 19, this should be included. |
The big question I have for the maintainers is when might the v19.0.0 release be coming. |
This is meant to address #7249. The doc outlines the pros and cons of various approaches React could use to handle attributes and properties on custom elements.
TOC/Summary
Background
When React tries to pass data to a custom element it always does so using HTML attributes.
Because attributes must be serialized to strings, this approach creates problems when the data being passed is an object or array. In that scenario, we end up with something like:
The workaround for this is to use a
ref
to manually set the property.This workaround feels a bit unnecessary as the majority of custom elements being shipped today are written with libraries which automatically generate JavaScript properties that back all of their exposed attributes. And anyone hand-authoring a vanilla custom element is encouraged to follow this practice as well. We'd like to ideally see runtime communication with custom elements in React use JavaScript properties by default.
This doc outlines a few proposals for how React could be updated to make this happen.
Proposals
Option 1: Only set properties
Rather than try to decide if a property or attribute should be set, React could always set properties on custom elements. React would NOT check to see if the property exists on the element beforehand.
Example:
The above code would result in React setting the
.bar
property of thex-foo
element equal to the value ofbaz
.For camelCased property names, React could use the same style it uses today for properties like
tabIndex
.Pros
Easy to understand/implement
This model is simple, explicit, and dovetails with React’s "JavaScript-centric API to the DOM".
Any element created with libraries like Polymer or Skate will automatically generate properties to back their exposed attributes. These elements should all "just work" with the above approach. Developers hand-authoring vanilla components are encouraged to back attributes with properties as that mirrors how modern (i.e. not oddballs like
<input>
) HTML5 elements (<video>
,<audio>
, etc.) have been implemented.Avoids conflict with future global attributes
When React sets an attribute on a custom element there’s always the risk that a future version of HTML will ship a similarly named attribute and break things. This concern was discussed with spec authors but there is no clear solution to the problem. Avoiding attributes entirely (except when a developer explicitly sets one using
ref
) may sidestep this issue until the browsers come up with a better solution.Takes advantage of custom element "upgrade"
Custom elements can be lazily upgraded on the page and some PRPL patterns rely on this technique. During the upgrade process, a custom element can access the properties passed to it by React—even if those properties were set before the definition loaded—and use them to render initial state.
Custom elements treated like any other React component
When React components pass data to one another they already use properties. This would just make custom elements behave the same way.
Cons
Possibly a breaking change
If a developer has been hand-authoring vanilla custom elements which only have an attributes API, then they will need to update their code or their app will break. The fix would be to use a
ref
to set the attribute (explained below).Need ref to set attribute
By changing the behavior so properties are preferred, it means developers will need to use a
ref
in order to explicitly set an attribute on a custom element.This is just a reversal of the current behavior where developers need a
ref
in order to set a property. Since developers should rarely need to set attributes on custom elements, this seems like a reasonable trade-off.Not clear how server-side rendering would work
It's not clear how this model would map to server-side rendering custom elements. React could assume that the properties map to similarly named attributes and attempt to set those on the server, but this is far from bulletproof and would possibly require a heuristic for things like camelCased properties -> dash-cased attributes.
Option 2: Properties-if-available
At runtime React could attempt to detect if a property is present on a custom element. If the property is present React will use it, otherwise it will fallback to setting an attribute. This is the model Preact uses to deal with custom elements.
Pseudocode implementation:
Possible steps:
If an element has a defined property, React will use it.
If an element has an undefined property, and React is trying to pass it primitive data (string/number/boolean), it will use an attribute.
If an element has an undefined property, and React is trying to pass it an object/array it will set it as a property. This is because some-attr="[object Object]” is not useful.
If the element is being rendered on the server, and React is trying to pass it a string/number/boolean, it will use an attribute.
If the element is being rendered on the server, and React is trying to pass it a object/array, it will not do anything.
Pros
Non-breaking change
It is possible to create a custom element that only uses attributes as its interface. This authoring style is NOT encouraged, but it may happen regardless. If a custom element author is relying on this behavior then this change would be non-breaking for them.
Cons
Developers need to understand the heuristic
Developers might be confused when React sets an attribute instead of a property depending on how they’ve chosen to load their element.
Falling back to attributes may conflict with future globals
Sebastian raised a concern that using
in
to check for the existence of a property on a custom element might accidentally detect a property on the superclass (HTMLElement).There are also other potential conflicts with global attributes discussed previously in this doc.
Option 3: Differentiate properties with a sigil
React could continue setting attributes on custom elements, but provide a sigil that developers could use to explicitly set properties instead. This is similar to the approach used by Glimmer.js.
Glimmer example:
In the above example, the @ sigil indicates that
src
andhiResSrc
should pass data to the custom element using properties, andwidth
should be serialized to an attribute string.Because React components already pass data to one another using properties, there would be no need for them to use the sigil (although it would work if they did, it would just be redundant). Instead, it would primarily be used as an explicit instruction to pass data to a custom element using JavaScript properties.
h/t to @developit of Preact for suggesting this approach :)
Pros
Non-breaking change that developers can opt-in to
All pre-existing React + custom element apps would continue to work exactly as they have. Developers could choose if they wanted to update their code to use the new sigil style.
Similar to how other libraries handle attributes/properties
Similar to Glimmer, both Angular and Vue use modifiers to differentiate between attributes and properties.
Vue example:
Angular example:
The system is explicit
Developers can tell React exactly what they want instead of relying on a heuristic like the properties-if-available approach.
Cons
It’s new syntax
Developers need to be taught how to use it and it needs to be thoroughly tested to make sure it is backwards compatible.
Not clear how server-side rendering would work
Should the sigil switch to using a similarly named attribute?
Option 4: Add an attributes object
React could add additional syntax which lets authors explicitly pass data as attributes. If developers do not use this attributes object, then their data will be passed using JavaScript properties.
Example:
This idea was originally proposed by @treshugart, author of Skate.js, and is implemented in the val library.
Pros
The system is explicit
Developers can tell React exactly what they want instead of relying on a heuristic like the properties-if-available approach.
Extending syntax may also solve issues with event handling
Note: This is outside the scope of this document but maybe worth mentioning :)
Issue #7901 requests that React bypass its synthetic event system when declarative event handlers are added to custom elements. Because custom element event names are arbitrary strings, it means they can be capitalized in any fashion. To bypass the synthetic event system today will also mean needing to come up with a heuristic for mapping event names from JSX to
addEventListener
.However, if the syntax is extended to allow attributes it could also be extended to allow events as well:
In this model the variable name is used as the event name. No heuristic is needed.
Cons
It’s new syntax
Developers need to be taught how to use it and it needs to be thoroughly tested to make sure it is backwards compatible.
It may be a breaking change
If any components already rely on properties named
attrs
orevents
, it could break them.It may be a larger change than any of the previous proposals
For React 17 it may be easier to make an incremental change (like one of the previous proposals) and position this proposal as something to take under consideration for a later, bigger refactor.
Option 5: An API for consuming custom elements
This proposal was offered by @sophiebits and @gaearon from the React team
React could create a new API for consuming custom elements that maps the element’s behavior with a configuration object.
Pseudocode example:
The above code returns a proxy component,
XFoo
that knows how to pass data to a custom element depending on the configuration you provide. You would use this proxy component in your app instead of using the custom element directly.Example usage:
Pros
The system is explicit
Developers can tell React the exact behavior they want.
Non-breaking change
Developers can opt-in to using the object or continue using the current system.
Idiomatic to React
This change doesn’t require new JSX syntax, and feels more like other APIs in React. For example, PropTypes (even though it’s being moved into its own package) has a somewhat similar approach.
Cons
Could be a lot of work for a complex component
Polymer’s paper-input element has 37 properties, so it would produce a very large config. If developers are using a lot of custom elements in their app, that may equal a lot of configs they need to write.
May bloat bundle size
Related to the above point, each custom element class now incurs the cost of its definition + its config object size.
Note: I'm not 100% sure if this is true. Someone more familiar with the React build process could verify.
Config needs to keep pace with the component
Every time the component does a minor version revision that adds a new property, the config will need to be updated as well. That’s not difficult, but it does add maintenance. Maybe if configs are generated from source this is less of a burden, but that may mean needing to create a new tool to generate configs for each web component library.
cc @sebmarkbage @gaearon @developit @treshugart @justinfagnani
The text was updated successfully, but these errors were encountered: