Thus far in our article series, we've taken a look at how React handles reactivity, server rendering, and how to send data back and forth between our React-based server and our client.
In particular, our last article outlined how we can send data from the server down to the client and back:
This is a great almost bi-directional communication from React Server Components and back.
Why do you say "almost"? What's missing?
Well, once you send an action back to the server, how do you get a response back from the server? What happens if the server action needs to inform you of some status?
Well, this is where useFormStatus and useFormState come into play:
What is useFormStatus?
useFormStatus allows developers to listen for state changes on their React Server Actions. IE: When a server action is pending or not.
While useFormStatus isn't directly a way to listen for changes from the server (instead it relies on the information on the client to show its metadata) it allows us to make a nicer user experience by showing a loading indicator while the server is taking its action.
Let's start with a client-side actions demo:
import { useFormStatus } from 'react-dom';
function Submit() {
const status = useFormStatus();
return (
<button disabled={status.pending}>
{status.pending ? 'Sending...' : 'Send'}
</button>
);
}
function App() {
async function waitASecond() {
await new Promise((resolve) => {
setTimeout(() => {
resolve();
}, 1000);
});
}
return (
<form action={waitASecond}>
<Submit />
</form>
);
}
Here, we're using the pending field on useFormStatus to tell us when our form is being submitted.
A note about
useFormStatus:
You might be wondering why I've extracted theSubmitcomponent into its own function. This is becauseuseFormStatusis a hook that implicitly gathers its state from the parent<form>element.If you were to use
useFormStatusinside of theAppcomponent, it would not work as expected. This is because theAppcomponent is not a child of the<form>element.For example, the following code would not work as expected:
// This code does not work, as `useFormStatus` is not a child of the <form> element function App() { async function waitASecond() { await new Promise((resolve) => { setTimeout(() => { resolve(); }, 1000); }); } const status = useFormStatus(); return ( <form action={waitASecond}> <button disabled={status.pending}> {status.pending ? 'Sending...' : 'Send'} </button> </form> ); }
useFormStatus usage with server actions
But of course it works with server actions as well. Let's adapt our todo list example from our last article:
// page.jsx
import { Todo } from "./client";
import { addTodoToDatabase, getTodos } from "./todos";
export default async function Home() {
const todos = await getTodos();
async function addTodo(formData) {
"use server";
const todo = formData.get("todo");
await addTodoToDatabase(todo);
}
return <Todo todos={todos} addTodo={addTodo} />;
}
// client.jsx
"use client";
import { useCallback } from "react";
import { useFormStatus } from "react-dom";
function TodoFormInner() {
const status = useFormStatus();
return (
<>
{status.pending && <p>Adding todo...</p>}
<input disabled={status.pending} name="todo" />
<button disabled={status.pending} type="submit">
Add Todo
</button>
</>
);
}
export function Todo({ todos, addTodo }) {
const addTodoAndRefresh = useCallback(async (formData) => {
await addTodo(formData);
window.location.reload();
}, []);
return (
<>
<form action={addTodoAndRefresh}>
<TodoFormInner />
</form>
<ul>
{todos.map((todo) => {
return <li key={todo.id}>{todo.value}</li>;
})}
</ul>
</>
);
}
What is useFormState?
useFormState allows us to get a response from a React Server Action and handle the results any way we might want to; including (but not limited to) displaying the contents of the response to the client.
This is a simple example of what useFormState looks like on client-side form actions:
function App() {
async function sayHi() {
await new Promise((resolve) => {
setTimeout(() => {
resolve();
}, 1000);
});
return 'Value from the action';
}
// State will be updated when `sayHi` returns a value
const [state, action] = useFormState(sayHi, 'Initial value');
return (
// Pass the action from `useFormState`
<form action={action}>
<p>{state}</p>
<button>Submit</button>
</form>
);
}
We can even implement a simple counter by utilizing the previous state (or initial value if there is no previous state):
async function increment(previousState, formData) {
return previousState + 1;
}
function App() {
const [state, action] = useFormState(increment, 0);
return (
<form action={action}>
<p>{state}</p>
<button>Increment</button>
</form>
)
}
This increment example comes from the React docs for the Hook.
useFormState usage with server actions
While useFormState works on the client-side, it's the most useful in conjuncture with server actions.
Let's add some form validation to our todo list application so that the user can't submit an empty field:
// page.jsx
import { Todo } from "./client";
import { addTodoToDatabase, getTodos } from "./todos";
import { redirect } from "next/navigation";
export default async function Home() {
const todos = await getTodos();
async function addTodo(previousState, formData) {
"use server";
const todo = formData.get("todo");
if (!todo) return "Please enter a todo";
await addTodoToDatabase(todo);
redirect("/");
}
return <Todo todos={todos} addTodo={addTodo} />;
}
// client.jsx
"use client";
import { useFormState } from "react-dom";
export function Todo({ todos, addTodo }) {
const [state, action] = useFormState(addTodo, "")
return (
<>
<form action={action}>
{state && <p>{state}</p>}
<input name="todo" />
<button type="submit">
Add Todo
</button>
</form>
<ul>
{todos.map((todo) => {
return <li key={todo.id}>{todo.value}</li>;
})}
</ul>
</>
);
}
Don't forget the API changes:
Don't forget that
useFormStaterequires you to change your server action to include a new first argument forpreviousState. Otherwise you'll get the following error:⨯ app\page.jsx (10:24) @ get ⨯ TypeError: formData.get is not a function
useFormState usage without client-side JavaScript
Because useFormState utilizes the <form> element's native action attribute under-the-hood, it works even without JavaScript enabled.
Assume you have the above sample code, but you have JavaScript disabled. When you click the submit button, the form will submit to the action attribute, and the page will refresh with the new information for the user.
Keep in mind that any client-side React code will not run if JavaScript is disabled. This includes the
useEffectHook among others.
How to use useFormState and useFormStatus together
You may have noticed that useFormState doesn't provide us the same pending information that useFormStatus does. Let's combine them for the ultimate user experience:
// page.jsx
import { Todo } from "./client";
import { addTodoToDatabase, getTodos } from "./todos";
import { redirect } from "next/navigation";
export default async function Home() {
const todos = await getTodos();
async function addTodo(previousState, formData) {
"use server";
const todo = formData.get("todo");
if (!todo) return "Please enter a todo";
await addTodoToDatabase(todo);
redirect("/");
}
return <Todo todos={todos} addTodo={addTodo} />;
}
// client.jsx
"use client";
import { useFormState, useFormStatus } from "react-dom";
function TodoFormInner() {
const status = useFormStatus();
return (
<>
{status.pending && <p>Adding todo...</p>}
<input disabled={status.pending} name="todo" />
<button disabled={status.pending} type="submit">
Add Todo
</button>
</>
);
}
export function Todo({ todos, addTodo }) {
const [state, action] = useFormState(addTodo, "");
return (
<>
<form action={action}>
{state && <p>{state}</p>}
<TodoFormInner />
</form>
<ul>
{todos.map((todo) => {
return <li key={todo.id}>{todo.value}</li>;
})}
</ul>
</>
);
}
Conclusion
And with that, that's our article series! We've covered a lot of ground; everything from how React's most fundamental values like reactivity works to advanced bi-directional data flow from the server and back!
Want to keep learning React from lil' ole' me? Well shucks; first thank you for reading!
But I can oblige! I've written a book called "The Framework Field Guide" that teaches React, Angular, and Vue all-at-once, in-depth, and for free. Check it out and let me know what you think.
Top comments (0)