Skip to content

Commit 81f1520

Browse files
brianjobrianjo
authored
Adds Reference Overview Page (#6378)
* Adds landing page for reference section.) * Updated hyperlinks. * Fixes Legacy APIs link. * Removes canary image from heading.
1 parent 4bdb87b commit 81f1520

File tree

3 files changed

+164
-130
lines changed

3 files changed

+164
-130
lines changed

‎src/content/reference/react/hooks.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
title: "Built-in React Hooks"
3+
---
4+
5+
<Intro>
6+
7+
*Hooks* let you use different React features from your components. You can either use the built-in Hooks or combine them to build your own. This page lists all built-in Hooks in React.
8+
9+
</Intro>
10+
11+
---
12+
13+
## State Hooks {/*state-hooks*/}
14+
15+
*State* lets a component ["remember" information like user input.](/learn/state-a-components-memory) For example, a form component can use state to store the input value, while an image gallery component can use state to store the selected image index.
16+
17+
To add state to a component, use one of these Hooks:
18+
19+
* [`useState`](/reference/react/useState) declares a state variable that you can update directly.
20+
* [`useReducer`](/reference/react/useReducer) declares a state variable with the update logic inside a [reducer function.](/learn/extracting-state-logic-into-a-reducer)
21+
22+
```js
23+
function ImageGallery() {
24+
const [index, setIndex] = useState(0);
25+
// ...
26+
```
27+
28+
---
29+
30+
## Context Hooks {/*context-hooks*/}
31+
32+
*Context* lets a component [receive information from distant parents without passing it as props.](/learn/passing-props-to-a-component) For example, your app's top-level component can pass the current UI theme to all components below, no matter how deep.
33+
34+
* [`useContext`](/reference/react/useContext) reads and subscribes to a context.
35+
36+
```js
37+
function Button() {
38+
const theme = useContext(ThemeContext);
39+
// ...
40+
```
41+
42+
---
43+
44+
## Ref Hooks {/*ref-hooks*/}
45+
46+
*Refs* let a component [hold some information that isn't used for rendering,](/learn/referencing-values-with-refs) like a DOM node or a timeout ID. Unlike with state, updating a ref does not re-render your component. Refs are an "escape hatch" from the React paradigm. They are useful when you need to work with non-React systems, such as the built-in browser APIs.
47+
48+
* [`useRef`](/reference/react/useRef) declares a ref. You can hold any value in it, but most often it's used to hold a DOM node.
49+
* [`useImperativeHandle`](/reference/react/useImperativeHandle) lets you customize the ref exposed by your component. This is rarely used.
50+
51+
```js
52+
function Form() {
53+
const inputRef = useRef(null);
54+
// ...
55+
```
56+
57+
---
58+
59+
## Effect Hooks {/*effect-hooks*/}
60+
61+
*Effects* let a component [connect to and synchronize with external systems.](/learn/synchronizing-with-effects) This includes dealing with network, browser DOM, animations, widgets written using a different UI library, and other non-React code.
62+
63+
* [`useEffect`](/reference/react/useEffect) connects a component to an external system.
64+
65+
```js
66+
function ChatRoom({ roomId }) {
67+
useEffect(() => {
68+
const connection = createConnection(roomId);
69+
connection.connect();
70+
return () => connection.disconnect();
71+
}, [roomId]);
72+
// ...
73+
```
74+
75+
Effects are an "escape hatch" from the React paradigm. Don't use Effects to orchestrate the data flow of your application. If you're not interacting with an external system, [you might not need an Effect.](/learn/you-might-not-need-an-effect)
76+
77+
There are two rarely used variations of `useEffect` with differences in timing:
78+
79+
* [`useLayoutEffect`](/reference/react/useLayoutEffect) fires before the browser repaints the screen. You can measure layout here.
80+
* [`useInsertionEffect`](/reference/react/useInsertionEffect) fires before React makes changes to the DOM. Libraries can insert dynamic CSS here.
81+
82+
---
83+
84+
## Performance Hooks {/*performance-hooks*/}
85+
86+
A common way to optimize re-rendering performance is to skip unnecessary work. For example, you can tell React to reuse a cached calculation or to skip a re-render if the data has not changed since the previous render.
87+
88+
To skip calculations and unnecessary re-rendering, use one of these Hooks:
89+
90+
- [`useMemo`](/reference/react/useMemo) lets you cache the result of an expensive calculation.
91+
- [`useCallback`](/reference/react/useCallback) lets you cache a function definition before passing it down to an optimized component.
92+
93+
```js
94+
function TodoList({ todos, tab, theme }) {
95+
const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);
96+
// ...
97+
}
98+
```
99+
100+
Sometimes, you can't skip re-rendering because the screen actually needs to update. In that case, you can improve performance by separating blocking updates that must be synchronous (like typing into an input) from non-blocking updates which don't need to block the user interface (like updating a chart).
101+
102+
To prioritize rendering, use one of these Hooks:
103+
104+
- [`useTransition`](/reference/react/useTransition) lets you mark a state transition as non-blocking and allow other updates to interrupt it.
105+
- [`useDeferredValue`](/reference/react/useDeferredValue) lets you defer updating a non-critical part of the UI and let other parts update first.
106+
107+
---
108+
109+
## Resource Hooks {/*resource-hooks*/}
110+
111+
*Resources* can be accessed by a component without having them as part of their state. For example, a component can read a message from a Promise or read styling information from a context.
112+
113+
To read a value from a resource, use this Hook:
114+
115+
- [`use`](/reference/react/use) lets you read the value of a resource like a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context).
116+
117+
```js
118+
function MessageComponent({ messagePromise }) {
119+
const message = use(messagePromise);
120+
const theme = use(ThemeContext);
121+
// ...
122+
}
123+
```
124+
125+
---
126+
127+
## Other Hooks {/*other-hooks*/}
128+
129+
These Hooks are mostly useful to library authors and aren't commonly used in the application code.
130+
131+
- [`useDebugValue`](/reference/react/useDebugValue) lets you customize the label React DevTools displays for your custom Hook.
132+
- [`useId`](/reference/react/useId) lets a component associate a unique ID with itself. Typically used with accessibility APIs.
133+
- [`useSyncExternalStore`](/reference/react/useSyncExternalStore) lets a component subscribe to an external store.
134+
135+
---
136+
137+
## Your own Hooks {/*your-own-hooks*/}
138+
139+
You can also [define your own custom Hooks](/learn/reusing-logic-with-custom-hooks#extracting-your-own-custom-hook-from-a-component) as JavaScript functions.

‎src/content/reference/react/index.md‎

Lines changed: 20 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,30 @@
11
---
2-
title: "Built-in React Hooks"
2+
title: React Reference Overview
33
---
44

55
<Intro>
6-
7-
*Hooks* let you use different React features from your components. You can either use the built-in Hooks or combine them to build your own. This page lists all built-in Hooks in React.
8-
6+
This section provides detailed reference documentation for working with React.
7+
For an introduction to React, please visit the [Learn](/learn) section.
98
</Intro>
109

11-
---
12-
13-
## State Hooks {/*state-hooks*/}
14-
15-
*State* lets a component ["remember" information like user input.](/learn/state-a-components-memory) For example, a form component can use state to store the input value, while an image gallery component can use state to store the selected image index.
16-
17-
To add state to a component, use one of these Hooks:
18-
19-
* [`useState`](/reference/react/useState) declares a state variable that you can update directly.
20-
* [`useReducer`](/reference/react/useReducer) declares a state variable with the update logic inside a [reducer function.](/learn/extracting-state-logic-into-a-reducer)
21-
22-
```js
23-
function ImageGallery() {
24-
const [index, setIndex] = useState(0);
25-
// ...
26-
```
27-
28-
---
29-
30-
## Context Hooks {/*context-hooks*/}
31-
32-
*Context* lets a component [receive information from distant parents without passing it as props.](/learn/passing-props-to-a-component) For example, your app's top-level component can pass the current UI theme to all components below, no matter how deep.
33-
34-
* [`useContext`](/reference/react/useContext) reads and subscribes to a context.
35-
36-
```js
37-
function Button() {
38-
const theme = useContext(ThemeContext);
39-
// ...
40-
```
41-
42-
---
43-
44-
## Ref Hooks {/*ref-hooks*/}
45-
46-
*Refs* let a component [hold some information that isn't used for rendering,](/learn/referencing-values-with-refs) like a DOM node or a timeout ID. Unlike with state, updating a ref does not re-render your component. Refs are an "escape hatch" from the React paradigm. They are useful when you need to work with non-React systems, such as the built-in browser APIs.
47-
48-
* [`useRef`](/reference/react/useRef) declares a ref. You can hold any value in it, but most often it's used to hold a DOM node.
49-
* [`useImperativeHandle`](/reference/react/useImperativeHandle) lets you customize the ref exposed by your component. This is rarely used.
50-
51-
```js
52-
function Form() {
53-
const inputRef = useRef(null);
54-
// ...
55-
```
56-
57-
---
58-
59-
## Effect Hooks {/*effect-hooks*/}
60-
61-
*Effects* let a component [connect to and synchronize with external systems.](/learn/synchronizing-with-effects) This includes dealing with network, browser DOM, animations, widgets written using a different UI library, and other non-React code.
62-
63-
* [`useEffect`](/reference/react/useEffect) connects a component to an external system.
64-
65-
```js
66-
function ChatRoom({ roomId }) {
67-
useEffect(() => {
68-
const connection = createConnection(roomId);
69-
connection.connect();
70-
return () => connection.disconnect();
71-
}, [roomId]);
72-
// ...
73-
```
10+
Our The React reference documentation is broken down into functional subsections:
7411

75-
Effects are an "escape hatch" from the React paradigm. Don't use Effects to orchestrate the data flow of your application. If you're not interacting with an external system, [you might not need an Effect.](/learn/you-might-not-need-an-effect)
12+
## React {/*react*/}
13+
Programmatic React features:
14+
* [Hooks](/reference/react/hooks) - Use different React features from your components.
15+
* [Components](/reference/react/components) - Documents built-in components that you can use in your JSX.
16+
* [APIs](/reference/react/apis) - APIs that are useful for defining components.
17+
* [Directives](/reference/react/directives) - Provide instructions to bundlers compatible with React Server Components.
7618

77-
There are two rarely used variations of `useEffect` with differences in timing:
78-
79-
* [`useLayoutEffect`](/reference/react/useLayoutEffect) fires before the browser repaints the screen. You can measure layout here.
80-
* [`useInsertionEffect`](/reference/react/useInsertionEffect) fires before React makes changes to the DOM. Libraries can insert dynamic CSS here.
81-
82-
---
83-
84-
## Performance Hooks {/*performance-hooks*/}
85-
86-
A common way to optimize re-rendering performance is to skip unnecessary work. For example, you can tell React to reuse a cached calculation or to skip a re-render if the data has not changed since the previous render.
87-
88-
To skip calculations and unnecessary re-rendering, use one of these Hooks:
89-
90-
- [`useMemo`](/reference/react/useMemo) lets you cache the result of an expensive calculation.
91-
- [`useCallback`](/reference/react/useCallback) lets you cache a function definition before passing it down to an optimized component.
92-
93-
```js
94-
function TodoList({ todos, tab, theme }) {
95-
const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);
96-
// ...
97-
}
98-
```
99-
100-
Sometimes, you can't skip re-rendering because the screen actually needs to update. In that case, you can improve performance by separating blocking updates that must be synchronous (like typing into an input) from non-blocking updates which don't need to block the user interface (like updating a chart).
101-
102-
To prioritize rendering, use one of these Hooks:
103-
104-
- [`useTransition`](/reference/react/useTransition) lets you mark a state transition as non-blocking and allow other updates to interrupt it.
105-
- [`useDeferredValue`](/reference/react/useDeferredValue) lets you defer updating a non-critical part of the UI and let other parts update first.
106-
107-
---
108-
109-
## Resource Hooks {/*resource-hooks*/}
110-
111-
*Resources* can be accessed by a component without having them as part of their state. For example, a component can read a message from a Promise or read styling information from a context.
112-
113-
To read a value from a resource, use this Hook:
114-
115-
- [`use`](/reference/react/use) lets you read the value of a resource like a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context).
116-
117-
```js
118-
function MessageComponent({ messagePromise }) {
119-
const message = use(messagePromise);
120-
const theme = use(ThemeContext);
121-
// ...
122-
}
123-
```
124-
125-
---
126-
127-
## Other Hooks {/*other-hooks*/}
128-
129-
These Hooks are mostly useful to library authors and aren't commonly used in the application code.
130-
131-
- [`useDebugValue`](/reference/react/useDebugValue) lets you customize the label React DevTools displays for your custom Hook.
132-
- [`useId`](/reference/react/useId) lets a component associate a unique ID with itself. Typically used with accessibility APIs.
133-
- [`useSyncExternalStore`](/reference/react/useSyncExternalStore) lets a component subscribe to an external store.
134-
135-
---
19+
## React DOM {/*react-dom*/}
20+
React-dom contains features that are only supported for web applications
21+
(which run in the browser DOM environment). This section is broken into the following:
13622

137-
## Your own Hooks {/*your-own-hooks*/}
23+
* [Hooks](/reference/react-dom/hooks) - Hooks for web applications which run in the browser DOM environment.
24+
* [Components](/reference/react-dom/components) - React supports all of the browser built-in HTML and SVG components.
25+
* [APIs](/reference/react-dom) - The `react-dom` package contains methods supported only in web applications.
26+
* [Client APIs](/reference/react-dom/client) - The `react-dom/client` APIs let you render React components on the client (in the browser).
27+
* [Server APIs](/reference/react-dom/server) - The `react-dom/server` APIs let you render React components to HTML on the server.
13828

139-
You can also [define your own custom Hooks](/learn/reusing-logic-with-custom-hooks#extracting-your-own-custom-hook-from-a-component) as JavaScript functions.
29+
## Legacy APIs {/*legacy-apis*/}
30+
* [Legacy APIs](/reference/react/legacy) - Exported from the react package, but not recommended for use in newly written code.

‎src/sidebarReference.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@
66
"hasSectionHeader": true,
77
"sectionHeader": "react@18.2.0"
88
},
9+
{
10+
"title": "Overview",
11+
"path": "/reference/react"
12+
},
913
{
1014
"title": "Hooks",
11-
"path": "/reference/react",
15+
"path": "/reference/react/hooks",
1216
"routes": [
1317
{
1418
"title": "use",

0 commit comments

Comments
 (0)