mirror of
https://github.com/facebook/react.git
synced 2025-11-01 09:12:30 +00:00
Sebastian Markbåge
48ec17b865
In React DOM, in general, we don't differentiate between `null` and `undefined` because we expect to target DOM APIs. When we're setting a property on a Custom Element, in the new heuristic, the goal is to allow passing whatever data type instead of normalizing it. Switching between `undefined` and `null` as an explicit value should therefore be respected. However, in this mode if `undefined` is used for the initial value, we don't actually set the property at all. If passing `null` we will now initialize it to the value `null`. Meaning `undefined` kind of represents the default. ### Removing Properties There is a pretty complex edge case which is what should happen when a prop used to exist but was removed from the props object. This doesn't have any kind of defined semantics. It really should mean - return to "default". Because in the declarative world it means the same as if it was just created - i.e. we can't just leave it as it was. The closest might be `delete object.property` but that's not really the intended way that properties on custom elements / classes are supposed to operate. Additionally, for a property to even hit our heuristic it must pass the `in` test and must exist to being with so the default must have a value. Since the point of these properties is to contain any kind of type, there isn't really a conceptual default value. E.g. a numeric default value might be zero `0` while a default string might be empty `""` and default object might `null`. Additionally, the conceptual default can really be initialized to anything. There's also varied precedence in the ecosystem here and really no consensus. Anything we pick would be kind of wrong, so we used to just pick `null`. _The safest way to consume a Custom Element is to always pass the same set of props._ JS does have a concept of a "default value" though and that is described as the value `undefined`. That's why default argument / object property initializers are initialized if the value is `undefined`. The problem with using `undefined` as value is that [you shouldn't actually ever set the value of a class property to `undefined`](https://twitter.com/sebmarkbage/status/1774082540296388752). A property should always be initialized to some value. It can't be left missing and shouldn't be initialized to the value `undefined` for hidden class optimizations. If we just mutate it to be `undefined` it would be potentially bad for perf and shouldn't really be the value after removing property - it should be returned to default. Every property should really have a setter to be useful since it is what is used to trigger reactivity when it changes. Sometimes you can just use the properties passively when something else happens but most of the time it should be a setter but to reach parity with DOM it should really be always so that the active value can be normalized. Those setters can have default argument initializers to represent what the default value should be. Therefore Custom Element properties should be used like this: ```js class CustomElement extends HTMLElement { _textLabel = ''; _price = 0; _items = null; constructor() { super(); } set textLabel(value = '') { this._textLabel = value; } get textLabel() { return this._textLabel; } set price(value = 0) { this._price = value; } get price() { return this._price; } set items(value = null) { this._items = value; } get items() { return this._items; } } ``` The default initializer can be used to initialize a value back to its original default when `undefined` is passed to it. Therefore, we pass `undefined`, not because we expect that to be the value of a property but because that's the value that represents "return to default". This fixes #28203 but not really for the reason specified in the issue. We don't expect you to actually store the `undefined` value but to use a setter to set the property to something else that represents the default. When we initialize the element the first time, we won't set anything if it's the value `undefined` so we assume that the property initializers running in the constructor is going to set the same default value as if we set the property to `undefined`. cc @josepharhar
React · 
React is a JavaScript library for building user interfaces.
- Declarative: React makes it painless to create interactive UIs. Design simple views for each state in your application, and React will efficiently update and render just the right components when your data changes. Declarative views make your code more predictable, simpler to understand, and easier to debug.
- Component-Based: Build encapsulated components that manage their own state, then compose them to make complex UIs. Since component logic is written in JavaScript instead of templates, you can easily pass rich data through your app and keep the state out of the DOM.
- Learn Once, Write Anywhere: We don't make assumptions about the rest of your technology stack, so you can develop new features in React without rewriting existing code. React can also render on the server using Node and power mobile apps using React Native.
Learn how to use React in your project.
Installation
React has been designed for gradual adoption from the start, and you can use as little or as much React as you need:
- Use Quick Start to get a taste of React.
- Add React to an Existing Project to use as little or as much React as you need.
- Create a New React App if you're looking for a powerful JavaScript toolchain.
Documentation
You can find the React documentation on the website.
Check out the Getting Started page for a quick overview.
The documentation is divided into several sections:
- Quick Start
- Tutorial
- Thinking in React
- Installation
- Describing the UI
- Adding Interactivity
- Managing State
- Advanced Guides
- API Reference
- Where to Get Support
- Contributing Guide
You can improve it by sending pull requests to this repository.
Examples
We have several examples on the website. Here is the first one to get you started:
import { createRoot } from 'react-dom/client';
function HelloMessage({ name }) {
return <div>Hello {name}</div>;
}
const root = createRoot(document.getElementById('container'));
root.render(<HelloMessage name="Taylor" />);
This example will render "Hello Taylor" into a container on the page.
You'll notice that we used an HTML-like syntax; we call it JSX. JSX is not required to use React, but it makes code more readable, and writing it feels like writing HTML.
Contributing
The main purpose of this repository is to continue evolving React core, making it faster and easier to use. Development of React happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving React.
Code of Conduct
Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
Contributing Guide
Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to React.
Good First Issues
To help you get your feet wet and get you familiar with our contribution process, we have a list of good first issues that contain bugs that have a relatively limited scope. This is a great place to get started.
License
React is MIT licensed.