You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/blog/2024/02/15/react-labs-what-we-have-been-working-on-february-2024.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -52,7 +52,7 @@ We refer to this broader collection of features as simply "Actions". Actions all
52
52
</form>
53
53
```
54
54
55
-
The `action` function can operate synchronously or asynchronously. You can define them on the client side using standard JavaScript or on the server with the [`'use server'`](/reference/react/use-server) directive. When using an action, React will manage the life cycle of the data submission for you, providing hooks like [`useFormStatus`](/reference/react-dom/hooks/useFormStatus), and [`useFormState`](/reference/react-dom/hooks/useFormState) to access the current state and response of the form action.
55
+
The `action` function can operate synchronously or asynchronously. You can define them on the client side using standard JavaScript or on the server with the [`'use server'`](/reference/react/use-server) directive. When using an action, React will manage the life cycle of the data submission for you, providing hooks like [`useFormStatus`](/reference/react-dom/hooks/useFormStatus), and [`useActionState`](/reference/react/useActionState) to access the current state and response of the form action.
56
56
57
57
By default, Actions are submitted within a [transition](/reference/react/useTransition), keeping the current page interactive while the action is processing. Since Actions support async functions, we've also added the ability to use `async/await` in transitions. This allows you to show pending UI with the `isPending` state of a transition when an async request like `fetch` starts, and show the pending UI all the way through the update being applied.
58
58
@@ -78,7 +78,7 @@ React Server Components, Asset Loading, Document Metadata, and Actions have all
78
78
79
79
-**Asset Loading**: we integrated Suspense with the loading lifecycle of resources such as stylesheets, fonts, and scripts so that React takes them into account to determine whether the content in elements like [`<style>`](/reference/react-dom/components/style), [`<link>`](/reference/react-dom/components/link), and [`<script>`](/reference/react-dom/components/script) are ready to be displayed. We’ve also added new [Resource Loading APIs](/reference/react-dom#resource-preloading-apis) like `preload` and `preinit` to provide greater control for when a resource should load and initialize.
80
80
81
-
-**Actions**: As shared above, we've added Actions to manage sending data from the client to the server. You can add `action` to elements like [`<form/>`](/reference/react-dom/components/form), access the status with [`useFormStatus`](/reference/react-dom/hooks/useFormStatus), handle the result with [`useFormState`](/reference/react-dom/hooks/useFormState), and optimistically update the UI with [`useOptimistic`](/reference/react/useOptimistic).
81
+
-**Actions**: As shared above, we've added Actions to manage sending data from the client to the server. You can add `action` to elements like [`<form/>`](/reference/react-dom/components/form), access the status with [`useFormStatus`](/reference/react-dom/hooks/useFormStatus), handle the result with [`useActionState`](/reference/react/useActionState), and optimistically update the UI with [`useOptimistic`](/reference/react/useOptimistic).
82
82
83
83
Since all of these features work together, it’s difficult to release them in the Stable channel individually. Releasing Actions without the complementary hooks for accessing form states would limit the practical usability of Actions. Introducing React Server Components without integrating Server Actions would complicate modifying data on the server.
Copy file name to clipboardExpand all lines: src/content/reference/react-dom/components/form.md
+6-6
Original file line number
Diff line number
Diff line change
@@ -324,14 +324,14 @@ Displaying a form submission error message before the JavaScript bundle loads fo
324
324
325
325
1.`<form>` be rendered by a [Server Component](/reference/react/use-client)
326
326
1. the function passed to the `<form>`'s `action` prop be a [Server Action](/reference/react/use-server)
327
-
1. the `useFormState` Hook be used to display the error message
327
+
1. the `useActionState` Hook be used to display the error message
328
328
329
-
`useFormState` takes two parameters: a [Server Action](/reference/react/use-server) and an initial state. `useFormState` returns two values, a state variable and an action. The action returned by `useFormState` should be passed to the `action` prop of the form. The state variable returned by `useFormState` can be used to displayed an error message. The value returned by the [Server Action](/reference/react/use-server) passed to `useFormState` will be used to update the state variable.
329
+
`useActionState` takes two parameters: a [Server Action](/reference/react/use-server) and an initial state. `useActionState` returns two values, a state variable and an action. The action returned by `useActionState` should be passed to the `action` prop of the form. The state variable returned by `useActionState` can be used to displayed an error message. The value returned by the [Server Action](/reference/react/use-server) passed to `useActionState` will be used to update the state variable.
330
330
331
331
<Sandpack>
332
332
333
333
```js src/App.js
334
-
import { useFormState } from"react-dom";
334
+
import { useActionState } from"react";
335
335
import { signUpNewUser } from"./api";
336
336
337
337
exportdefaultfunctionPage() {
@@ -345,12 +345,12 @@ export default function Page() {
Copy file name to clipboardExpand all lines: src/content/reference/react/use-server.md
+4-4
Original file line number
Diff line number
Diff line change
@@ -133,7 +133,7 @@ By passing a Server Action to the form `action`, React can [progressively enhanc
133
133
134
134
In the username request form, there might be the chance that a username is not available. `requestUsername` should tell us if it fails or not.
135
135
136
-
To update the UI based on the result of a Server Action while supporting progressive enhancement, use [`useFormState`](/reference/react-dom/hooks/useFormState).
136
+
To update the UI based on the result of a Server Action while supporting progressive enhancement, use [`useActionState`](/reference/react/useActionState).
137
137
138
138
```js
139
139
// requestUsername.js
@@ -153,11 +153,11 @@ export default async function requestUsername(formData) {
Copy file name to clipboardExpand all lines: src/content/reference/react/useActionState.md
+29-25
Original file line number
Diff line number
Diff line change
@@ -1,20 +1,26 @@
1
1
---
2
-
title: useFormState
2
+
title: useActionState
3
3
canary: true
4
4
---
5
5
6
6
<Canary>
7
7
8
-
The `useFormState` Hook is currently only available in React's Canary and experimental channels. Learn more about [release channels here](/community/versioning-policy#all-release-channels). In addition, you need to use a framework that supports [React Server Components](/reference/react/use-client) to get the full benefit of `useFormState`.
8
+
The `useActionState` Hook is currently only available in React's Canary and experimental channels. Learn more about [release channels here](/community/versioning-policy#all-release-channels). In addition, you need to use a framework that supports [React Server Components](/reference/react/use-client) to get the full benefit of `useActionState`.
9
9
10
10
</Canary>
11
11
12
+
<Note>
13
+
14
+
In earlier React Canary versions, this API was part of React DOM and called `useFormState`.
15
+
16
+
</Note>
17
+
12
18
<Intro>
13
19
14
-
`useFormState` is a Hook that allows you to update state based on the result of a form action.
20
+
`useActionState` is a Hook that allows you to update state based on the result of a form action.
{/* TODO T164397693: link to actions documentation once it exists */}
31
37
32
-
Call `useFormState` at the top level of your component to create component state that is updated [when a form action is invoked](/reference/react-dom/components/form). You pass `useFormState` an existing form action function as well as an initial state, and it returns a new action that you use in your form, along with the latest form state. The latest form state is also passed to the function that you provided.
38
+
Call `useActionState` at the top level of your component to create component state that is updated [when a form action is invoked](/reference/react-dom/components/form). You pass `useActionState` an existing form action function as well as an initial state, and it returns a new action that you use in your form, along with the latest form state. The latest form state is also passed to the function that you provided.
The form state is the value returned by the action when the form was last submitted. If the form has not yet been submitted, it is the initial state that you pass.
53
59
54
-
If used with a Server Action, `useFormState` allows the server's response from submitting the form to be shown even before hydration has completed.
60
+
If used with a Server Action, `useActionState` allows the server's response from submitting the form to be shown even before hydration has completed.
55
61
56
62
[See more examples below.](#usage)
57
63
@@ -65,30 +71,30 @@ If used with a Server Action, `useFormState` allows the server's response from s
65
71
66
72
#### Returns {/*returns*/}
67
73
68
-
`useFormState` returns an array with exactly two values:
74
+
`useActionState` returns an array with exactly two values:
69
75
70
76
1. The current state. During the first render, it will match the `initialState` you have passed. After the action is invoked, it will match the value returned by the action.
71
77
2. A new action that you can pass as the `action` prop to your `form` component or `formAction` prop to any `button` component within the form.
72
78
73
79
#### Caveats {/*caveats*/}
74
80
75
-
* When used with a framework that supports React Server Components, `useFormState` lets you make forms interactive before JavaScript has executed on the client. When used without Server Components, it is equivalent to component local state.
76
-
* The function passed to `useFormState` receives an extra argument, the previous or initial state, as its first argument. This makes its signature different than if it were used directly as a form action without using `useFormState`.
81
+
* When used with a framework that supports React Server Components, `useActionState` lets you make forms interactive before JavaScript has executed on the client. When used without Server Components, it is equivalent to component local state.
82
+
* The function passed to `useActionState` receives an extra argument, the previous or initial state, as its first argument. This makes its signature different than if it were used directly as a form action without using `useActionState`.
77
83
78
84
---
79
85
80
86
## Usage {/*usage*/}
81
87
82
88
### Using information returned by a form action {/*using-information-returned-by-a-form-action*/}
83
89
84
-
Call `useFormState` at the top level of your component to access the return value of an action from the last time a form was submitted.
90
+
Call `useActionState` at the top level of your component to access the return value of an action from the last time a form was submitted.
`useFormState` returns an array with exactly two items:
107
+
`useActionState` returns an array with exactly two items:
102
108
103
109
1. The <CodeStep step={1}>current state</CodeStep> of the form, which is initially set to the <CodeStep step={4}>initial state</CodeStep> you provided, and after the form is submitted is set to the return value of the <CodeStep step={3}>action</CodeStep> you provided.
104
110
2. A <CodeStep step={2}>new action</CodeStep> that you pass to `<form>` as its `action` prop.
105
111
106
112
When the form is submitted, the <CodeStep step={3}>action</CodeStep> function that you provided will be called. Its return value will become the new <CodeStep step={1}>current state</CodeStep> of the form.
107
113
108
-
The <CodeStep step={3}>action</CodeStep> that you provide will also receive a new first argument, namely the <CodeStep step={1}>current state</CodeStep> of the form. The first time the form is submitted, this will be the <CodeStep step={4}>initial state</CodeStep> you provided, while with subsequent submissions, it will be the return value from the last time the action was called. The rest of the arguments are the same as if `useFormState` had not been used.
114
+
The <CodeStep step={3}>action</CodeStep> that you provide will also receive a new first argument, namely the <CodeStep step={1}>current state</CodeStep> of the form. The first time the form is submitted, this will be the <CodeStep step={4}>initial state</CodeStep> you provided, while with subsequent submissions, it will be the return value from the last time the action was called. The rest of the arguments are the same as if `useActionState` had not been used.
109
115
110
116
```js [[3, 1, "action"], [1, 1, "currentState"]]
111
117
functionaction(currentState, formData) {
@@ -118,17 +124,16 @@ function action(currentState, formData) {
118
124
119
125
#### Display form errors {/*display-form-errors*/}
120
126
121
-
To display messages such as an error message or toast that's returned by a Server Action, wrap the action in a call to `useFormState`.
127
+
To display messages such as an error message or toast that's returned by a Server Action, wrap the action in a call to `useActionState`.
### My action can no longer read the submitted form data {/*my-action-can-no-longer-read-the-submitted-form-data*/}
285
289
286
-
When you wrap an action with `useFormState`, it gets an extra argument *as its first argument*. The submitted form data is therefore its *second* argument instead of its first as it would usually be. The new first argument that gets added is the current state of the form.
290
+
When you wrap an action with `useActionState`, it gets an extra argument *as its first argument*. The submitted form data is therefore its *second* argument instead of its first as it would usually be. The new first argument that gets added is the current state of the form.
0 commit comments