Mastering Form State with useActionState

The Problem with Form State

Handling form submissions in React can get messy. You often find yourself juggling loading states, error messages, and the actual submitted data. Traditionally, this involves a lot of useState calls, prop drilling, or even context. It works, but it’s not always the most elegant or straightforward approach, especially as forms grow in complexity.

Imagine a typical form. You need to know if it’s submitting, if there was an error, and what the response was. You might have something like this:

1
import React, { useState } from 'react';
2

3
function MyForm() {
4
  const [formData, setFormData] = useState({ name: '', email: '' });
5
  const [isLoading, setIsLoading] = useState(false);
6
  const [error, setError] = useState(null);
7
  const [successMessage, setSuccessMessage] = useState(null);
8

9
  const handleChange = (e) => {
10
    setFormData({ ...formData, [e.target.name]: e.target.value });
11
  };
12

13
  const handleSubmit = async (e) => {
14
    e.preventDefault();
15
    setIsLoading(true);
16
    setError(null);
17
    setSuccessMessage(null);
18

19
    try {
20
      const response = await fetch('/api/submit', {
21
        method: 'POST',
22
        headers: { 'Content-Type': 'application/json' },
23
        body: JSON.stringify(formData),
24
      });
25

26
      if (!response.ok) {
27
        const errorData = await response.json();
28
        throw new Error(errorData.message || 'Something went wrong');
29
      }
30

31
      const result = await response.json();
32
      setSuccessMessage(result.message);
33
      setFormData({ name: '', email: '' }); // Clear form on success
34
    } catch (err) {
35
      setError(err.message);
36
    } finally {
37
      setIsLoading(false);
38
    }
39
  };
40

41
  return (
42
    <form onSubmit={handleSubmit}>
43
      {error && <p style={{ color: 'red' }}>Error: {error}</p>}
44
      {successMessage && <p style={{ color: 'green' }}>{successMessage}</p>}
45
      <div>
46
        <label>Name:</label>
47
        <input type="text" name="name" value={formData.name} onChange={handleChange} />
48
      </div>
49
      <div>
50
        <label>Email:</label>
51
        <input type="email" name="email" value={formData.email} onChange={handleChange} />
52
      </div>
53
      <button type="submit" disabled={isLoading}>
54
        {isLoading ? 'Submitting...' : 'Submit'}
55
      </button>
56
    </form>
57
  );
58
}
59

60
export default MyForm;

See all those useState calls? isLoading, error, successMessage? It gets repetitive fast.

Introducing `useActionState`

React 19 (or versions of React where this hook is available) introduces useActionState. This hook is designed specifically to simplify managing the state associated with an asynchronous action, like a form submission. It consolidates the loading, error, and data states into a single hook.

useActionState takes two arguments:

A reducer function (similar to useReducer) that handles state transitions.
An initial state value.

It returns an array containing:

The current state.
A function to dispatch an action to the reducer.
A pending state indicator (boolean).

Let’s refactor the previous example using useActionState.

A Cleaner Approach

First, we need a reducer function. This function will define how our state changes based on actions. In the context of a form submission, actions might be ‘SUBMITTING’, ‘RESOLVED’ (success), or ‘REJECTED’ (error).

1
export function formReducer(state, action) {
2
  switch (action.type) {
3
    case 'SUBMITTING':
4
      return { ...state, isSubmitting: true, error: null, successMessage: null };
5
    case 'RESOLVED':
6
      return { ...state, isSubmitting: false, successMessage: action.payload.message, error: null };
7
    case 'REJECTED':
8
      return { ...state, isSubmitting: false, error: action.payload.error, successMessage: null };
9
    default:
10
      return state;
11
  }
12
}

Now, let’s integrate this into our form component using useActionState.

1
import React, { useState, useActionState } from 'react';
2
import { formReducer } from './reducer';
3

4
const initialState = {
5
  isSubmitting: false,
6
  error: null,
7
  successMessage: null,
8
};
9

10
async function submitFormData(formData) {
11
  // This is where your actual API call would go
12
  // For demonstration, let's simulate a delay and potential error
13
  return new Promise((resolve, reject) => {
14
    setTimeout(() => {
15
      if (formData.name === "Test" || formData.email === "error@example.com") {
16
        reject({ message: "Invalid input detected!" });
17
      } else {
18
        resolve({ message: `Thank you, ${formData.name}! Your submission was successful.` });
19
      }
20
    }, 1500);
21
  });
22
}
23

24
function OptimizedForm() {
25
  const [formState, formDispatch, isPending] = useActionState(
26
    async (state, formData) => {
27
      formDispatch({ type: 'SUBMITTING' }); // Dispatch SUBMITTING action manually
28
      try {
29
        const result = await submitFormData(formData);
30
        formDispatch({ type: 'RESOLVED', payload: result });
31
      } catch (err) {
32
        formDispatch({ type: 'REJECTED', payload: { error: err.message } });
33
      }
34
    },
35
    initialState
36
  );
37

38
  const [formData, setFormData] = useState({ name: '', email: '' });
39

40
  const handleChange = (e) => {
41
    setFormData({ ...formData, [e.target.name]: e.target.value });
42
  };
43

44
  const handleSubmit = async (e) => {
45
    e.preventDefault();
46
    // useActionState's returned dispatch function isn't directly used for the async operation,
47
    // but rather the action creator is invoked in the form submission handler.
48
    // The reducer handles the state updates based on the async operation's outcome.
49
    await formDispatch(formData); // Dispatching the form data to the action creator
50
  };
51

52
  return (
53
    <form onSubmit={handleSubmit}>
54
      {formState.error && <p style={{ color: 'red' }}>Error: {formState.error}</p>}
55
      {formState.successMessage && <p style={{ color: 'green' }}>{formState.successMessage}</p>}
56
      <div>
57
        <label>Name:</label>
58
        <input type="text" name="name" value={formData.name} onChange={handleChange} disabled={isPending} />
59
      </div>
60
      <div>
61
        <label>Email:</label>
62
        <input type="email" name="email" value={formData.email} onChange={handleChange} disabled={isPending} />
63
      </div>
64
      <button type="submit" disabled={isPending}>
65
        {isPending ? 'Submitting...' : 'Submit'}
66
      </button>
67
    </form>
68
  );
69
}
70

71
export default OptimizedForm;

In this refactored version:

The reducer (formReducer) dictates state changes.
useActionState manages the asynchronous operation’s lifecycle.
isPending directly gives us the loading state.
The formState object holds our error and successMessage.

This pattern centralizes form state management, making your code cleaner and easier to reason about. It’s a welcome addition for anyone building complex forms in React applications.

Why it’s better

useActionState doesn’t replace useState or useReducer entirely. Instead, it offers a more focused solution for a common problem: orchestrating the state around actions. By separating the action logic from the component’s UI concerns and providing built-in state for pending operations, it leads to more declarative and less error-prone form handling. This is especially beneficial when dealing with server mutations and complex UI feedback loops.

Tags: React 19, Web Development, Form Handling, Hooks

The Problem with Form State

Introducing useActionState

A Cleaner Approach

Why it’s better

Contents

Introducing `useActionState`