🪝 Introduction to useActionState
The useActionState Hook is a React Hook that helps manage the state returned by an action. It is especially useful when working with forms, allowing the result of an action—such as a success message, validation errors, or submitted data—to be stored and displayed automatically.
Important
🎯 Why Use useActionState?
Traditional form handling often requires multiple state variables to track loading, success, and error messages. useActionState centralizes this logic by allowing an action to return the next state after execution.
- Manage form submission results.
- Handle validation messages.
- Display success or error states.
- Reduce manual state management.
⚙️ Syntax
Basic Syntax
const [state, formAction, isPending] =
useActionState(action, initialState);| Part | Description |
|---|---|
| state | The latest state returned by the action. |
| formAction | The action passed to a form or invoked during submission. |
| isPending | Indicates whether the action is currently running. |
| initialState | The initial state before the first action runs. |
🔄 How useActionState Works
💻 Example 1: Basic Form
Simple Form Action
import { useActionState } from "react";
async function submitForm(previousState, formData) {
return {
message: "Form submitted successfully!"
};
}
function ContactForm() {
const [state, formAction, isPending] =
useActionState(submitForm, {
message: ""
});
return (
<form action={formAction}>
<input
name="name"
placeholder="Your name"
/>
<button disabled={isPending}>
Submit
</button>
<p>{state.message}</p>
</form>
);
}When the form is submitted, the action executes and returns a new state. React automatically updates the component with the latest message.
💻 Example 2: Validation
Validation Example
import { useActionState } from "react";
async function validate(previousState, formData) {
const email = formData.get("email");
if (!email) {
return {
error: "Email is required."
};
}
return {
success: "Form submitted!"
};
}The returned object becomes the new state, allowing validation messages or success messages to be displayed without manually managing multiple state variables.
📊 Traditional State vs useActionState
| Traditional Form State | useActionState |
|---|---|
| Manual state updates. | State updates automatically from the action. |
| Multiple state variables. | Single action-driven state. |
| More boilerplate. | Cleaner and more organized code. |
| Separate loading management. | isPending indicates whether the action is running. |
📅 Action Lifecycle
The user submits the form.
React calls the action function.
isPending becomes true while the action runs.
The action returns the next state.
React updates the component with the new state.
🎯 Common Use Cases
Manage form submissions and display submission results.
Return validation errors directly from an action.
Handle login or registration responses with a single state object.
Show success messages, error messages, or other feedback after an action completes.
⚠️ Common Mistakes
- Using useActionState for unrelated local component state.
- Ignoring the isPending value when disabling form controls.
- Returning inconsistent state shapes from different action paths.
- Mixing unrelated responsibilities into a single action.
Warning
✅ Best Practices
- Use useActionState for action-driven state such as forms.
- Return consistent objects from every action result.
- Use isPending to disable buttons or show loading indicators.
- Separate validation logic from presentation whenever possible.
- Keep action functions simple, predictable, and reusable.
📚 Official Resource
Learn more about useActionState in the official React documentation at React useActionState Documentation.