Rename useFormState to useActionState

src/content/blog/2024/02/15/react-labs-what-we-have-been-working-on-february-2024.md

@@ -52,7 +52,7 @@ We refer to this broader collection of features as simply "Actions". Actions all
 </form>
 ```
 
-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. 
+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.
 
 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. 
 
@@ -78,7 +78,7 @@ React Server Components, Asset Loading, Document Metadata, and Actions have all
 
 - **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.
 
-- **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).
+- **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).
 
 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. 
 

src/content/reference/react-dom/components/form.md

@@ -324,14 +324,14 @@ Displaying a form submission error message before the JavaScript bundle loads fo
 
 1. `<form>` be rendered by a [Server Component](/reference/react/use-client)
 1. the function passed to the `<form>`'s `action` prop be a [Server Action](/reference/react/use-server)
-1. the `useFormState` Hook be used to display the error message
+1. the `useActionState` Hook be used to display the error message
 
-`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.
+`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.
 
 <Sandpack>
 
 ```js src/App.js
-import { useFormState } from "react-dom";
+import { useActionState } from "react";
 import { signUpNewUser } from "./api";
 
 export default function Page() {
@@ -345,12 +345,12 @@ export default function Page() {
       return err.toString();
     }
   }
-  const [message, formAction] = useFormState(signup, null);
+  const [message, signupAction] = useActionState(signup, null);
   return (
     <>
       <h1>Signup for my newsletter</h1>
       <p>Signup with the same email twice to see an error</p>
-      <form action={formAction} id="signup-form">
+      <form action={signupAction} id="signup-form">
         <label htmlFor="email">Email: </label>
         <input name="email" id="email" placeholder="[email protected]" />
         <button>Sign up</button>
@@ -386,7 +386,7 @@ export async function signUpNewUser(newEmail) {
 
 </Sandpack>
 
-Learn more about updating state from a form action with the [`useFormState`](/reference/react-dom/hooks/useFormState) docs
+Learn more about updating state from a form action with the [`useActionState`](/reference/react/hooks/useActionState) docs
 
 ### Handling multiple submission types {/*handling-multiple-submission-types*/}
 

src/content/reference/react-dom/hooks/index.md

@@ -21,14 +21,13 @@ Form Hooks are currently only available in React's canary and experimental chann
 *Forms* let you create interactive controls for submitting information.  To manage forms in your components, use one of these Hooks:
 
 * [`useFormStatus`](/reference/react-dom/hooks/useFormStatus) allows you to make updates to the UI based on the status of the a form.
-* [`useFormState`](/reference/react-dom/hooks/useFormState) allows you to manage state inside a form.
 
 ```js
 function Form({ action }) {
   async function increment(n) {
     return n + 1;
   }
-  const [count, incrementFormAction] = useFormState(increment, 0);
+  const [count, incrementFormAction] = useActionState(increment, 0);
   return (
     <form action={action}>
       <button formAction={incrementFormAction}>Count: {count}</button>
@@ -46,4 +45,3 @@ function Button() {
   );
 }
 ```
-

src/content/reference/react/hooks.md

@@ -113,6 +113,7 @@ These Hooks are mostly useful to library authors and aren't commonly used in the
 - [`useDebugValue`](/reference/react/useDebugValue) lets you customize the label React DevTools displays for your custom Hook.
 - [`useId`](/reference/react/useId) lets a component associate a unique ID with itself. Typically used with accessibility APIs.
 - [`useSyncExternalStore`](/reference/react/useSyncExternalStore) lets a component subscribe to an external store.
+* [`useActionState`](/reference/react/useActionState) allows you to manage state of actions.
 
 ---
 

src/content/reference/react/use-server.md

@@ -133,7 +133,7 @@ By passing a Server Action to the form `action`, React can [progressively enhanc
 
 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.
 
-To update the UI based on the result of a Server Action while supporting progressive enhancement, use [`useFormState`](/reference/react-dom/hooks/useFormState).
+To update the UI based on the result of a Server Action while supporting progressive enhancement, use [`useActionState`](/reference/react/useActionState).
 
 ```js
 // requestUsername.js
@@ -153,11 +153,11 @@ export default async function requestUsername(formData) {
 // UsernameForm.js
 'use client';
 
-import { useFormState } from 'react-dom';
+import { useActionState } from 'react';
 import requestUsername from './requestUsername';
 
 function UsernameForm() {
-  const [returnValue, action] = useFormState(requestUsername, 'n/a');
+  const [returnValue, action] = useActionState(requestUsername, 'n/a');
 
   return (
     <>
@@ -171,7 +171,7 @@ function UsernameForm() {
 }
 ```
 
-Note that like most Hooks, `useFormState` can only be called in <CodeStep step={1}>[client code](/reference/react/use-client)</CodeStep>.
+Note that like most Hooks, `useActionState` can only be called in <CodeStep step={1}>[client code](/reference/react/use-client)</CodeStep>.
 
 ### Calling a Server Action outside of `<form>` {/*calling-a-server-action-outside-of-form*/}
 

src/content/reference/react-dom/hooks/useFormState.md → src/content/reference/react/useActionState.md

@@ -1,20 +1,26 @@
 ---
-title: useFormState
+title: useActionState
 canary: true
 ---
 
 <Canary>
 
-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`.
+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`.
 
 </Canary>
 
+<Note>
+
+In earlier React Canary versions, this API was part of React DOM and called `useFormState`.
+
+</Note>
+
 <Intro>
 
-`useFormState` is a Hook that allows you to update state based on the result of a form action.
+`useActionState` is a Hook that allows you to update state based on the result of a form action.
 
 ```js
-const [state, formAction] = useFormState(fn, initialState, permalink?);
+const [state, formAction] = useActionState(fn, initialState, permalink?);
 ```
 
 </Intro>
@@ -25,21 +31,21 @@ const [state, formAction] = useFormState(fn, initialState, permalink?);
 
 ## Reference {/*reference*/}
 
-### `useFormState(action, initialState, permalink?)` {/*useformstate*/}
+### `useActionState(action, initialState, permalink?)` {/*useactionstate*/}
 
 {/* TODO T164397693: link to actions documentation once it exists */}
 
-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.
+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.
 
 ```js
-import { useFormState } from "react-dom";
+import { useActionState } from "react";
 
 async function increment(previousState, formData) {
   return previousState + 1;
 }
 
 function StatefulForm({}) {
-  const [state, formAction] = useFormState(increment, 0);
+  const [state, formAction] = useActionState(increment, 0);
   return (
     <form>
       {state}
@@ -51,7 +57,7 @@ function StatefulForm({}) {
 
 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.
 
-If used with a Server Action, `useFormState` allows the server's response from submitting the form to be shown even before hydration has completed.
+If used with a Server Action, `useActionState` allows the server's response from submitting the form to be shown even before hydration has completed.
 
 [See more examples below.](#usage)
 
@@ -65,30 +71,30 @@ If used with a Server Action, `useFormState` allows the server's response from s
 
 #### Returns {/*returns*/}
 
-`useFormState` returns an array with exactly two values:
+`useActionState` returns an array with exactly two values:
 
 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.
 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.
 
 #### Caveats {/*caveats*/}
 
-* 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.
-* 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`.
+* 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.
+* 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`.
 
 ---
 
 ## Usage {/*usage*/}
 
 ### Using information returned by a form action {/*using-information-returned-by-a-form-action*/}
 
-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.
+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.
 
 ```js [[1, 5, "state"], [2, 5, "formAction"], [3, 5, "action"], [4, 5, "null"], [2, 8, "formAction"]]
-import { useFormState } from 'react-dom';
+import { useActionState } from 'react';
 import { action } from './actions.js';
 
 function MyComponent() {
-  const [state, formAction] = useFormState(action, null);
+  const [state, formAction] = useActionState(action, null);
   // ...
   return (
     <form action={formAction}>
@@ -98,14 +104,14 @@ function MyComponent() {
 }
 ```
 
-`useFormState` returns an array with exactly two items:
+`useActionState` returns an array with exactly two items:
 
 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.
 2. A <CodeStep step={2}>new action</CodeStep> that you pass to `<form>` as its `action` prop.
 
 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.
 
-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.
+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.
 
 ```js [[3, 1, "action"], [1, 1, "currentState"]]
 function action(currentState, formData) {
@@ -118,17 +124,16 @@ function action(currentState, formData) {
 
 #### Display form errors {/*display-form-errors*/}
 
-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`.
+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`.
 
 <Sandpack>
 
 ```js src/App.js
-import { useState } from "react";
-import { useFormState } from "react-dom";
+import { useActionState, useState } from "react";
 import { addToCart } from "./actions.js";
 
 function AddToCartForm({itemID, itemTitle}) {
-  const [message, formAction] = useFormState(addToCart, null);
+  const [message, formAction] = useActionState(addToCart, null);
   return (
     <form action={formAction}>
       <h2>{itemTitle}</h2>
@@ -196,12 +201,11 @@ The return value from a Server Action can be any serializable value. For example
 <Sandpack>
 
 ```js src/App.js
-import { useState } from "react";
-import { useFormState } from "react-dom";
+import { useActionState, useState } from "react";
 import { addToCart } from "./actions.js";
 
 function AddToCartForm({itemID, itemTitle}) {
-  const [formState, formAction] = useFormState(addToCart, {});
+  const [formState, formAction] = useActionState(addToCart, {});
   return (
     <form action={formAction}>
       <h2>{itemTitle}</h2>
@@ -283,7 +287,7 @@ form button {
 
 ### My action can no longer read the submitted form data {/*my-action-can-no-longer-read-the-submitted-form-data*/}
 
-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.
+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.
 
 ```js
 function action(currentState, formData) {

src/sidebarReference.json

@@ -14,6 +14,11 @@
       "title": "Hooks",
       "path": "/reference/react/hooks",
       "routes": [
+        {
+          "title": "useActionState",
+          "path": "/reference/react/useActionState",
+          "canary": true
+        },
         {
           "title": "useCallback",
           "path": "/reference/react/useCallback"
@@ -174,11 +179,6 @@
       "title": "Hooks",
       "path": "/reference/react-dom/hooks",
       "routes": [
-        {
-          "title": "useFormState",
-          "path": "/reference/react-dom/hooks/useFormState",
-          "canary": true
-        },
         {
           "title": "useFormStatus",
           "path": "/reference/react-dom/hooks/useFormStatus",

vercel.json

@@ -9,6 +9,11 @@
       "destination": "/reference/react",
       "permanent": true
     },
+    {
+      "source": "/reference/react-dom/hooks/useFormState",
+      "destination": "/reference/react/useActionState",
+      "permanent": true
+    },
     {
       "source": "/learn/meet-the-team",
       "destination": "/community/team",