Skip to content

Commit ada7d2f

Browse files
Docs: Add note about useActionState and useFormState React versions (#68880)
Warn users about React versions for `useFormState` vs. `useActionState`. - `useFormState` was renamed to `useActionState` in React 19 RC. - There are no React docs for `useFormState` that we can link to but the `useActionState` mentions the change. To avoid having to update all mentions of `useActionState` now, then update all mentions of `useFormState` in the future, I've kept the `useActionState` examples as is, and added a callout about the React versions in the pages that have `useActionState` examples.
1 parent 3e0bf6b commit ada7d2f

File tree

3 files changed

+10
-5
lines changed

3 files changed

+10
-5
lines changed

docs/02-app/01-building-your-application/01-routing/05-error-handling.mdx

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,18 @@ related:
88

99
Errors can be divided into two categories: **expected errors** and **uncaught exceptions**:
1010

11-
- **Model expected errors as return values**: Avoid using `try`/`catch` for expected errors in Server Actions. Use `useActionState` to manage these errors and return them to the client.
11+
- **Model expected errors as return values**: Avoid using `try`/`catch` for expected errors in Server Actions. Use [`useActionState`](https://react.dev/reference/react/useActionState) to manage these errors and return them to the client.
1212
- **Use error boundaries for unexpected errors**: Implement error boundaries using `error.tsx` and `global-error.tsx` files to handle unexpected errors and provide a fallback UI.
1313

14+
> **Good to know**: These examples use React's `useActionState` hook, which is available in React 19 RC. If you are using an earlier version of React, use `useFormState` instead. See the [React docs](https://react.dev/reference/react/useActionState) for more information.
15+
1416
## Handling Expected Errors
1517

1618
Expected errors are those that can occur during the normal operation of the application, such as those from [server-side form validation](/docs/app/building-your-application/data-fetching/server-actions-and-mutations#server-side-form-validation) or failed requests. These errors should be handled explicitly and returned to the client.
1719

1820
### Handling Expected Errors from Server Actions
1921

20-
Use the `useActionState` hook (previously `useFormState`) to manage the state of Server Actions, including handling errors. This approach avoids `try`/`catch` blocks for expected errors, which should be modeled as return values rather than thrown exceptions.
22+
Use the [`useActionState`](https://react.dev/reference/react/useActionState) hook to manage the state of Server Actions, including handling errors. This approach avoids `try`/`catch` blocks for expected errors, which should be modeled as return values rather than thrown exceptions.
2123

2224
```tsx filename="app/actions.ts" switcher
2325
'use server'

docs/02-app/01-building-your-application/02-data-fetching/03-server-actions-and-mutations.mdx

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,7 @@ This will trigger the submission of the nearest `<form>` ancestor, which will in
288288
289289
### Server-side form validation
290290
291-
We recommend using HTML validation like `required` and `type="email"` for basic client-side form validation.
291+
You can use the HTML attributes like `required` and `type="email"` for basic client-side form validation.
292292
293293
For more advanced server-side validation, you can use a library like [zod](https://zod.dev/) to validate the form fields before mutating the data:
294294
@@ -351,6 +351,8 @@ Once the fields have been validated on the server, you can return a serializable
351351
- By passing the action to `useActionState`, the action's function signature changes to receive a new `prevState` or `initialState` parameter as its first argument.
352352
- `useActionState` is a React hook and therefore must be used in a Client Component.
353353
354+
> **Good to know**: These examples use React's `useActionState` hook, which is available in React 19 RC. If you are using an earlier version of React, use `useFormState` instead. See the [React docs](https://react.dev/reference/react/useActionState) for more information.
355+
354356
```tsx filename="app/actions.ts" switcher
355357
'use server'
356358

@@ -440,7 +442,6 @@ export function Signup() {
440442
> **Good to know:**
441443
>
442444
> - Before mutating data, you should always ensure a user is also authorized to perform the action. See [Authentication and Authorization](#authentication-and-authorization).
443-
> - In earlier React Canary versions, this API was part of React DOM and called `useFormState`.
444445
445446
### Pending states
446447

docs/02-app/01-building-your-application/09-authentication/index.mdx

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,9 @@ The examples on this page walk through basic username and password auth for educ
2929

3030
### Sign-up and login functionality
3131

32-
You can use the [`<form>`](https://react.dev/reference/react-dom/components/form) element with React's [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations) and [`useActionState()`](https://react.dev/reference/react/useActionState) to capture user credentials, validate form fields, and call your Authentication Provider's API or database.
32+
> **Good to know**: These examples use React's `useActionState` hook, which is available in React 19 RC. If you are using an earlier version of React, use `useFormState` instead. See the [React docs](https://react.dev/reference/react/useActionState) for more information.
33+
34+
You can use the [`<form>`](https://react.dev/reference/react-dom/components/form) element with React's [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations) and [`useActionState`](https://react.dev/reference/react/useActionState) to capture user credentials, validate form fields, and call your Authentication Provider's API or database.
3335

3436
Since Server Actions always execute on the server, they provide a secure environment for handling authentication logic.
3537

0 commit comments

Comments
 (0)