From 948bce90ba873dc664d63756d4e94f7d1ea7c062 Mon Sep 17 00:00:00 2001 From: Dave McCabe Date: Thu, 5 Oct 2023 16:49:40 -0700 Subject: [PATCH 1/3] Add useFormState reference --- .../reference/react-dom/hooks/useFormState.md | 219 ++++++++++++++++++ src/sidebarReference.json | 11 + 2 files changed, 230 insertions(+) create mode 100644 src/content/reference/react-dom/hooks/useFormState.md diff --git a/src/content/reference/react-dom/hooks/useFormState.md b/src/content/reference/react-dom/hooks/useFormState.md new file mode 100644 index 00000000000..5a322674e10 --- /dev/null +++ b/src/content/reference/react-dom/hooks/useFormState.md @@ -0,0 +1,219 @@ +--- +title: useFormState +canary: true +--- + + + +The `useFormState` Hook is currently only available in React's canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +`useFormState` is a Hook that allows you to show error messages or other responses after submitting a form. + +```js +const [state, formAction] = useFormState(action, initalState); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `useFormState()` {/*useformstate*/} + +Call `useFormState` at the top level of your component to see the return value of an action after submitting a form. You pass `useFormState` an existing action as well as an initial state, and it returns a new action that you use when submitting your form, along with the latest form state. + +```js +function AddToCart({itemID}) { + const [message, formAction] = useFormState(addToCartAction, null); + return ( +
+ +
+ {message} + + ); +} + +export default function App() { + return ( + <> + + + + ) +} +``` + +```js actions.js +"use server"; + +export async function addToCart(prevState, queryData) { + const itemID = queryData.get('itemID'); + if (itemID === "1") { + return "Added to cart"; + } else { + return "Couldn't add to cart: the item is sold out."; + } +} +``` + +```css styles.css hidden +form { + border: solid 1px black; + margin-bottom: 24px; + padding: 12px +} +``` + +```json package.json hidden +{ + "dependencies": { + "react": "experimental", + "react-dom": "experimental", + "react-scripts": "^5.0.0" + }, + "main": "/index.js", + "devDependencies": {} +} +``` + + + +### Display structured information after submitting a form {/*display-structured-information-after-submitting-a-form*/} + +The return value from a server action can be any serializable value. For example, it could be an object that includes a boolean indicating whether the action was successful, an error message, or updated information. + + + +```js App.js +import { useState } from "react"; +import { experimental_useFormState as useFormState } from "react-dom"; +import { addToCart } from "./actions.js"; + +function AddToCartForm({itemID, itemTitle}) { + const [formState, formAction] = useFormState(addToCart, {}); + return ( +
+

{itemTitle}

+ + + {formState?.success && +
+ Added to cart! Your cart now has {formState.cartSize} items. +
+ } + {formState?.success === false && +
+ Failed to add to cart: {formState.message} +
+ } +
+ ); +} + +export default function App() { + return ( + <> + + + + ) +} +``` + +```js actions.js +"use server"; + +export async function addToCart(prevState, queryData) { + const itemID = queryData.get('itemID'); + if (itemID === "1") { + return { + success: true, + cartSize: 12, + }; + } else { + return { + success: false, + message: "The item is sold out.", + }; + } +} +``` + +```css styles.css hidden +form { + border: solid 1px black; + margin-bottom: 24px; + padding: 12px +} +``` + +```json package.json hidden +{ + "dependencies": { + "react": "experimental", + "react-dom": "experimental", + "react-scripts": "^5.0.0" + }, + "main": "/index.js", + "devDependencies": {} +} +``` + + diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 6272569370c..79dd377a83f 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -151,6 +151,17 @@ "hasSectionHeader": true, "sectionHeader": "react-dom@18.2.0" }, + { + "title": "Hooks", + "path": "/reference/react-dom/hooks", + "routes": [ + { + "title": "useFormState", + "path": "/reference/react-dom/hooks/useFormState", + "canary": true + } + ] + }, { "title": "Components", "path": "/reference/react-dom/components", From 26e24d2b355c12e278a6586c146d2c20993bba84 Mon Sep 17 00:00:00 2001 From: Dave McCabe Date: Fri, 6 Oct 2023 15:31:08 -0700 Subject: [PATCH 2/3] Matt's suggestions for useFormState reference --- .../reference/react-dom/hooks/useFormState.md | 90 +++++++++++++++++-- 1 file changed, 81 insertions(+), 9 deletions(-) diff --git a/src/content/reference/react-dom/hooks/useFormState.md b/src/content/reference/react-dom/hooks/useFormState.md index 5a322674e10..ca7af253611 100644 --- a/src/content/reference/react-dom/hooks/useFormState.md +++ b/src/content/reference/react-dom/hooks/useFormState.md @@ -5,13 +5,13 @@ canary: true -The `useFormState` Hook is currently only available in React's canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). +The `useFormState` Hook is currently only available in React's canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). In addition, you need to use a framework that supports React Server Components to get the full benefit of `useFormState`. -`useFormState` is a Hook that allows you to show error messages or other responses after submitting a form. +`useFormState` is a Hook that allows you to read the return value of the form action after a form is submitted. ```js const [state, formAction] = useFormState(action, initalState); @@ -27,6 +27,10 @@ const [state, formAction] = useFormState(action, initalState); ### `useFormState()` {/*useformstate*/} +In the context of React Server Components, an *action* is a function that may be [executed when a form is submitted](/reference/react-dom/components/form). You can execute actions on the server or on the client. + +{/* TODO T164397693: link to actions documentation once it exists */} + Call `useFormState` at the top level of your component to see the return value of an action after submitting a form. You pass `useFormState` an existing action as well as an initial state, and it returns a new action that you use when submitting your form, along with the latest form state. ```js @@ -52,9 +56,11 @@ If used with a server action, `useFormState` allows the server's response from s #### Parameters {/*parameters*/} -* `action`: The action to be performed when the form is submitted. It can be a server or a client action. When the action is called, it will receive the previous state of the form (initially the `initialState` that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that an action normally receives. +* `action`: The action to be performed when the form is submitted. When the action is called, it will receive the previous state of the form (initially the `initialState` that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that an action normally receives. * `initialState`: The value you want the state to be initially. It can be any serializable value. This argument is ignored after the form is first submitted. +{/* TODO T164397693: link to serializable values docs once it exists */} + #### Returns {/*returns*/} @@ -63,11 +69,53 @@ If used with a server action, `useFormState` allows the server's response from s 1. The current state. During the first render, it will match the `initialState` you have passed. After the form is submitted, 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. +#### 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, there is no advantage to using it over component local state. +* The action passed to `useFormState` receives an extra argument, the previous or initial state state, as its first argument. This makes its signature different than if it were used directly without `useFormState`. + --- ## Usage {/*usage*/} -### Display a message after submitting a form {/*display-a-message-after-submitting-a-form*/} +### 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. + +```js [[1, 5, "state"], [2, 5, "formAction"], [3, 5, "action"], [4, 5, "null"], [2, 8, "formAction"]] +import { useFormState } from 'react-dom'; +import { action } from './actions.js'; + +function MyComponent() { + const [state, formAction] = useFormState(action, null); + // ... + return ( +
+ {/* ... */} +
+ ); +} +``` + +`useFormState` returns an array with exactly two items: + +1. The current state of the form, which is initially set to the initial state you provided, and after the form is submitted is set to the return value of the action you provided. +2. A new action that you pass to `
` as its `action` prop. + +When the form is submitted, the action that you provided will be called. Its return value will become the new current state of the form. + +The action that you provide will also receive a new first argument, namely the current state of the form. The first time the form is submitted, this will be the initial state 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 + +```js [[3, 1, "action"], [1, 1, "currentState"]] +function action(currentState, formData) { + // ... + return 'next state'; +} +``` + + + +#### 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`. @@ -75,7 +123,7 @@ To display messages such as an error message or toast that's returned by a serve ```js App.js import { useState } from "react"; -import { experimental_useFormState as useFormState } from "react-dom"; +import { useFormState } from "react-dom"; import { addToCart } from "./actions.js"; function AddToCartForm({itemID, itemTitle}) { @@ -119,6 +167,10 @@ form { margin-bottom: 24px; padding: 12px } + +form button { + margin-right: 12px; +} ``` ```json package.json hidden @@ -132,10 +184,11 @@ form { "devDependencies": {} } ``` - + + -### Display structured information after submitting a form {/*display-structured-information-after-submitting-a-form*/} +#### Display structured information after submitting a form {/*display-structured-information-after-submitting-a-form*/} The return value from a server action can be any serializable value. For example, it could be an object that includes a boolean indicating whether the action was successful, an error message, or updated information. @@ -143,7 +196,7 @@ The return value from a server action can be any serializable value. For example ```js App.js import { useState } from "react"; -import { experimental_useFormState as useFormState } from "react-dom"; +import { useFormState } from "react-dom"; import { addToCart } from "./actions.js"; function AddToCartForm({itemID, itemTitle}) { @@ -202,6 +255,10 @@ form { margin-bottom: 24px; padding: 12px } + +form button { + margin-right: 12px; +} ``` ```json package.json hidden @@ -215,5 +272,20 @@ form { "devDependencies": {} } ``` - + + + + + +## Troubleshooting {/*troubleshooting*/} + +### 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. + +```js +function action(currentState, formData) { + // ... +} +``` From aa622cd2bf89906e70c099575c84caa43e72eac5 Mon Sep 17 00:00:00 2001 From: Dave McCabe Date: Wed, 25 Oct 2023 10:31:24 -0700 Subject: [PATCH 3/3] Incorporated PR feedback for useFormState --- .../reference/react-dom/hooks/index.md | 15 +++++ .../reference/react-dom/hooks/useFormState.md | 62 +++++++++---------- 2 files changed, 46 insertions(+), 31 deletions(-) create mode 100644 src/content/reference/react-dom/hooks/index.md diff --git a/src/content/reference/react-dom/hooks/index.md b/src/content/reference/react-dom/hooks/index.md new file mode 100644 index 00000000000..20f8f745c68 --- /dev/null +++ b/src/content/reference/react-dom/hooks/index.md @@ -0,0 +1,15 @@ +--- +title: "Built-in React DOM Hooks" +--- + + + +This page lists all built-in Hooks in React DOM. + + + +--- + +## Form Hooks {/*form-hooks*/} + +* [`useFormState`](/reference/react-dom/hooks/useFormState) allows you to update state based on the result of a form action. diff --git a/src/content/reference/react-dom/hooks/useFormState.md b/src/content/reference/react-dom/hooks/useFormState.md index ca7af253611..53c73ae3874 100644 --- a/src/content/reference/react-dom/hooks/useFormState.md +++ b/src/content/reference/react-dom/hooks/useFormState.md @@ -5,16 +5,16 @@ canary: true -The `useFormState` Hook is currently only available in React's canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). In addition, you need to use a framework that supports React Server Components to get the full benefit of `useFormState`. +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`. -`useFormState` is a Hook that allows you to read the return value of the form action after a form is submitted. +`useFormState` is a Hook that allows you to update state based on the result of a form action. ```js -const [state, formAction] = useFormState(action, initalState); +const [state, formAction] = useFormState(fn, initialState); ``` @@ -25,24 +25,25 @@ const [state, formAction] = useFormState(action, initalState); ## Reference {/*reference*/} -### `useFormState()` {/*useformstate*/} - -In the context of React Server Components, an *action* is a function that may be [executed when a form is submitted](/reference/react-dom/components/form). You can execute actions on the server or on the client. +### `useFormState(action, initialState)` {/*useformstate*/} {/* TODO T164397693: link to actions documentation once it exists */} -Call `useFormState` at the top level of your component to see the return value of an action after submitting a form. You pass `useFormState` an existing action as well as an initial state, and it returns a new action that you use when submitting your form, along with the latest form state. +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. ```js -function AddToCart({itemID}) { - const [message, formAction] = useFormState(addToCartAction, null); +import { useFormState } from "react-dom"; + +async function increment(previousState, formData) { + return previousState + 1; +} + +function StatefulForm({}) { + const [state, formAction] = useFormState(increment, 0); return ( - - - ) } @@ -56,23 +57,22 @@ If used with a server action, `useFormState` allows the server's response from s #### Parameters {/*parameters*/} -* `action`: The action to be performed when the form is submitted. When the action is called, it will receive the previous state of the form (initially the `initialState` that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that an action normally receives. -* `initialState`: The value you want the state to be initially. It can be any serializable value. This argument is ignored after the form is first submitted. +* `fn`: The function to be called when the form is submitted or button pressed. When the function is called, it will receive the previous state of the form (initially the `initialState` that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that a form action normally receives. +* `initialState`: The value you want the state to be initially. It can be any serializable value. This argument is ignored after the action is first invoked. {/* TODO T164397693: link to serializable values docs once it exists */} - #### Returns {/*returns*/} `useFormState` 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 form is submitted, 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. +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, there is no advantage to using it over component local state. -* The action passed to `useFormState` receives an extra argument, the previous or initial state state, as its first argument. This makes its signature different than if it were used directly without `useFormState`. +* 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`. --- @@ -102,7 +102,7 @@ function MyComponent() { 1. The current state of the form, which is initially set to the initial state you provided, and after the form is submitted is set to the return value of the action you provided. 2. A new action that you pass to `
` as its `action` prop. -When the form is submitted, the action that you provided will be called. Its return value will become the new current state of the form. +When the form is submitted, the action function that you provided will be called. Its return value will become the new current state of the form. The action that you provide will also receive a new first argument, namely the current state of the form. The first time the form is submitted, this will be the initial state 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 @@ -141,8 +141,8 @@ function AddToCartForm({itemID, itemTitle}) { export default function App() { return ( <> - - + + ) } @@ -176,8 +176,8 @@ form button { ```json package.json hidden { "dependencies": { - "react": "experimental", - "react-dom": "experimental", + "react": "canary", + "react-dom": "canary", "react-scripts": "^5.0.0" }, "main": "/index.js", @@ -223,8 +223,8 @@ function AddToCartForm({itemID, itemTitle}) { export default function App() { return ( <> - - + + ) } @@ -264,8 +264,8 @@ form button { ```json package.json hidden { "dependencies": { - "react": "experimental", - "react-dom": "experimental", + "react": "canary", + "react-dom": "canary", "react-scripts": "^5.0.0" }, "main": "/index.js",