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
{{ message }}
Repository navigation
Commit 8bce77f
Browse filesBrowse the repository at this point in the historyBrowse files
Enhance form documentation by expanding on the use of Server Functions in the action prop, including detailed examples for passing extra data and handling form submissions. Clarify the behavior of form elements and their interaction with FormData.
Copy file name to clipboardExpand all lines: src/content/reference/react-dom/components/form.md
+90-9Lines changed: 90 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -128,20 +128,57 @@ export default function Search() {
128
128
129
129
### Handling form submission with a Server Function {/*handle-form-submission-with-a-server-function*/}
130
130
131
-
Render a `<form>` with an input and submit button. Pass a Server Function (a function marked with [`'use server'`](/reference/rsc/use-server)) to the form's `action` prop to run the function when the form is submitted.
131
+
A `<form>`'s `action` prop can run a Server Function (a function marked with [`'use server'`](/reference/rsc/use-server)) when the user submits the form. Users can submit that form before JavaScript loads, and when JavaScript is disabled. This matches how forms behave when you pass a URL to `action`.
132
132
133
-
Passing a Server Function to a form's `action` prop allows users to submit the form before JavaScript loads or when JavaScript is disabled. This matches how forms behave when you pass a URL to `action`.
133
+
React calls the Server Function with the form's [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and includes every input with a `name` attribute. To pass additional data, such as an ID from props, see [Passing extra data to an Action](#passing-extra-data-to-an-action).
134
134
135
-
You can use hidden form fields to pass data to the Server Function. React includes the hidden field values in the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) passed to the function.
135
+
```jsx
136
+
import { addComment } from'./actions.js';
137
+
138
+
functionCommentForm() {
139
+
return (
140
+
<form action={addComment}>
141
+
<textarea name="comment"/>
142
+
<button type="submit">Comment</button>
143
+
</form>
144
+
);
145
+
}
146
+
```
147
+
148
+
```js
149
+
// actions.js
150
+
'use server';
151
+
152
+
exportasyncfunctionaddComment(formData) {
153
+
constcomment=formData.get('comment');
154
+
// ...
155
+
}
156
+
```
157
+
158
+
<DeepDive>
159
+
160
+
#### Passing extra data to an Action {/*passing-extra-data-to-an-action*/}
161
+
162
+
An Action receives the submitted [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData). To include data the user did not enter, such as an ID from props, use one of these approaches:
163
+
164
+
***Hidden fields** add the value to `FormData`. The value appears in the HTML, and `formData.get` returns a string. Users can submit the form before JavaScript loads.
165
+
***Binding with `bind`** passes the value as an argument to a Server Function, before `formData`. The argument keeps its type, so a number stays a number. It must be [serializable](/reference/rsc/use-server#serializable-parameters-and-return-values). Users can submit the form before JavaScript loads.
166
+
***A function in the component** reads props and state directly. It runs after JavaScript loads, then calls a Server Function with those values.
167
+
168
+
The client sends hidden field values and bound arguments. Check on the server that the logged-in user is allowed to perform the Action. See [Security considerations](/reference/rsc/use-server#security).
In a Server Component, render an `<input type="hidden">` with a `name` and `value`. React includes that value in the `FormData` passed to the Action.
136
173
137
174
```jsx
175
+
// Server Component
138
176
import { updateCart } from'./lib.js';
139
177
140
-
functionAddToCart({productId}) {
178
+
functionAddToCart({productId}) {
141
179
asyncfunctionaddToCart(formData) {
142
180
'use server';
143
-
constproductId=formData.get('productId');
144
-
awaitupdateCart(productId);
181
+
awaitupdateCart(formData.get('productId'));
145
182
}
146
183
return (
147
184
<form action={addToCart}>
@@ -152,12 +189,17 @@ function AddToCart({productId}) {
152
189
}
153
190
```
154
191
155
-
Instead of using a hidden form field, call the <CodeStepstep={1}>`bind`</CodeStep> method to pass an extra argument to the Server Function. This binds <CodeStepstep={2}>`productId`</CodeStep> as an argument before the <CodeStepstep={3}>`formData`</CodeStep> that React passes to the function.
192
+
React includes a submit button's `name` and `value` in `FormData` when that button submits the form.
193
+
194
+
#### Binding with `bind` {/*passing-extra-data-bind*/}
In a Server Component, call [`bind`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind) on the Server Function and pass the bound function to `action`. Pass `null` as the first argument to `bind`. Each argument after `null` comes before the `formData` argument React passes when the form is submitted.
197
+
198
+
```jsx
199
+
// Server Component
158
200
import { updateCart } from'./lib.js';
159
201
160
-
functionAddToCart({productId}) {
202
+
functionAddToCart({productId}) {
161
203
asyncfunctionaddToCart(productId, formData) {
162
204
'use server';
163
205
awaitupdateCart(productId);
@@ -171,6 +213,45 @@ function AddToCart({productId}) {
[`useActionState`](/reference/react/useActionState) passes the previous state before `FormData`. Bound arguments come first, so the Server Function receives the bound values, the previous state, and then `formData`. Define that function in a separate file and bind it from the Client Component.
219
+
220
+
#### A function in the component {/*passing-extra-data-function*/}
221
+
222
+
Define the function you pass to `action` in the Client Component that has the props or state. That function reads those values and passes them to a Server Function.
0 commit comments