useActionState trong React: form, lỗi và trạng thái chờ

useActionState là một hook của React 19, chạy một hàm bất đồng bộ (một action), lưu bất cứ thứ gì nó trả về làm state, và cho bạn biết nó có còn đang chạy hay không. Bạn gọi nó dưới dạng const [state, formAction, isPending] = useActionState(action, initialState) rồi truyền formAction cho một <form>.

import { useActionState } from 'react';

function subscribe(email) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(resolve, 1000));
}

async function joinList(previousState, formData) {
    const email = formData.get('email');
    if (!email.includes('@')) {
        return { ok: false, message: 'That does not look like an email.' };
    }
    await subscribe(email);
    return { ok: true, message: `Subscribed ${email}.` };
}

export default function App() {
    const [state, formAction, isPending] = useActionState(joinList, { ok: false, message: '' });

    return (
        <form action={formAction}>
            <input name="email" placeholder="you@example.com" />
            <button type="submit" disabled={isPending}>
                {isPending ? 'Subscribing...' : 'Subscribe'}
            </button>
            {state.message && (
                <p style={{ color: state.ok ? 'green' : 'crimson' }}>{state.message}</p>
            )}
        </form>
    );
}

Gửi form trống trước: action trả về một object lỗi và thông báo hiện ra. Sau đó gõ một địa chỉ có @ rồi gửi lại. Trong một giây, nút hiện "Subscribing..." và bị vô hiệu hóa.

Cú pháp

const [state, formAction, isPending] = useActionState(action, initialState, permalink?);

• action là hàm cần chạy. React gọi nó dưới dạng action(previousState, ...args). Bất cứ thứ gì nó trả về (hoặc resolve thành, nếu là hàm async) sẽ trở thành state mới.
• initialState là state trước khi action chạy lần nào. Hãy dùng cùng cấu trúc mà action trả về, để component đọc được state.message ngay cả ở lần render đầu.
• state là kết quả mới nhất.
• formAction là phiên bản đã được bọc của action. Truyền nó cho <form action> hoặc <button formAction>, hoặc tự gọi nó.
• isPending là true từ lúc action bắt đầu cho đến khi nó kết thúc.
• permalink là tùy chọn và chỉ có ý nghĩa với Server Function trong một framework: URL mà form sẽ chuyển tới nếu được gửi trước khi JavaScript tải xong.

Action nhận state trước đó làm đối số đầu tiên. Đây là lỗi phổ biến nhất khi chuyển một form sang cách này: viết async function save(formData) khiến formData chứa state cũ, và formData.get sẽ ném lỗi.

Đọc form bằng FormData

Khi formAction được dùng làm action của form, React gọi action của bạn với FormData của form. Mọi trường có name đều nằm trong đó. Bạn không cần useState cho các ô nhập hay trình xử lý onChange, và không cần gọi e.preventDefault(): React tự xử lý sự kiện submit.

import { useActionState } from 'react';

async function order(previousState, formData) {
    const entries = Object.fromEntries(formData);
    console.log('form data:', entries);
    return { count: previousState.count + 1, last: entries };
}

export default function App() {
    const [state, formAction] = useActionState(order, { count: 0, last: null });

    return (
        <form action={formAction}>
            <input name="dish" defaultValue="Ramen" />
            <select name="size" defaultValue="large">
                <option value="small">Small</option>
                <option value="large">Large</option>
            </select>
            <label>
                <input type="checkbox" name="spicy" defaultChecked /> Spicy
            </label>
            <button type="submit">Order</button>
            <p>Orders placed: {state.count}</p>
            {state.last && <p>Last: {state.last.size} {state.last.dish}</p>}
        </form>
    );
}

Bỏ chọn Spicy rồi gửi lại: khóa spicy biến mất khỏi dữ liệu được ghi log, vì một checkbox không được chọn sẽ không gửi gì cả. Action cũng đọc previousState.count để cộng thêm một, đó là lý do state trước đó đứng đầu.

Trả về lỗi kiểm tra dữ liệu

Việc kiểm tra dữ liệu nên nằm trong action. Trả về các lỗi như một phần của state, và trả về cả những giá trị người dùng đã gõ để form điền lại chúng. Sau khi một form action chạy xong, React đặt lại các trường uncontrolled của form, nên một trường không có defaultValue={state.values...} sẽ trống trơn sau một lần gửi thất bại.

import { useActionState } from 'react';

function createAccount(name) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(() => resolve({ id: 7, name }), 800));
}

async function signUp(previousState, formData) {
    const values = { name: formData.get('name'), password: formData.get('password') };
    const errors = {};
    if (values.name.trim().length < 2) errors.name = 'At least 2 characters.';
    if (values.password.length < 8) errors.password = 'At least 8 characters.';
    if (Object.keys(errors).length > 0) {
        return { values, errors, user: null };
    }
    const user = await createAccount(values.name);
    return { values: { name: '', password: '' }, errors: {}, user };
}

const initial = { values: { name: '', password: '' }, errors: {}, user: null };

export default function App() {
    const [state, formAction, isPending] = useActionState(signUp, initial);

    if (state.user) return <p>Welcome, {state.user.name} (account #{state.user.id}).</p>;

    return (
        <form action={formAction} style={{ display: 'grid', gap: 6, maxWidth: 240 }}>
            <input name="name" placeholder="Name" defaultValue={state.values.name} />
            {state.errors.name && <small style={{ color: 'crimson' }}>{state.errors.name}</small>}
            <input name="password" type="password" placeholder="Password" defaultValue={state.values.password} />
            {state.errors.password && <small style={{ color: 'crimson' }}>{state.errors.password}</small>}
            <button type="submit" disabled={isPending}>{isPending ? 'Creating...' : 'Create account'}</button>
        </form>
    );
}

Gõ một cái tên chỉ có một chữ cái và một mật khẩu ngắn, rồi gửi. Cả hai lỗi hiện ra và cả hai trường vẫn giữ những gì bạn đã gõ. Bỏ defaultValue={state.values.name} rồi gửi lại: trường tên tự xóa trắng sau khi báo lỗi.

Trong một ứng dụng thật, hãy để máy chủ là bên quyết định cuối cùng. Kiểm tra phía client cho phản hồi nhanh, nhưng ai cũng có thể gửi request mà không cần qua form của bạn.

Gọi action bên ngoài form

formAction là một hàm, nên một nút hay một effect cũng có thể gọi nó. Khi tự gọi, hãy bọc lời gọi trong startTransition. Form làm việc đó giúp bạn; một onClick thông thường thì không, và thiếu transition thì isPending không cập nhật đúng (React ghi một lỗi về chuyện này ở development).

import { startTransition, useActionState } from 'react';

function fetchNextPage(page) {
    // Stands in for a real request
    return new Promise((resolve) =>
        setTimeout(() => resolve([`Item ${page * 2 - 1}`, `Item ${page * 2}`]), 700),
    );
}

async function loadMore(previousState) {
    const page = previousState.page + 1;
    const items = await fetchNextPage(page);
    return { page, items: [...previousState.items, ...items] };
}

export default function App() {
    const [state, load, isPending] = useActionState(loadMore, { page: 0, items: [] });

    return (
        <div>
            <ul>
                {state.items.map((item) => (
                    <li key={item}>{item}</li>
                ))}
            </ul>
            <button onClick={() => startTransition(() => load())} disabled={isPending}>
                {isPending ? 'Loading...' : 'Load more'}
            </button>
        </div>
    );
}

Click Load more vài lần. Mỗi lần gọi bắt đầu từ state mà lần trước trả về, nên các trang được nối thêm theo đúng thứ tự. Nếu bạn gọi action lần nữa khi nó vẫn đang chạy, React đưa lời gọi vào hàng đợi và chạy nó sau lời gọi hiện tại, mỗi lần với state mới nhất.

useActionState đến từ đâu

Trước khi React 19 ra mắt, hook này có trong các bản build canary với tên useFormState, import từ react-dom. Nó được đổi tên thành useActionState, chuyển sang react và có thêm giá trị isPending. Nếu bạn gặp code cũ như dưới đây, chỉ cần sửa câu lệnh import và tên hook:

// React canary, before 19
import { useFormState } from 'react-dom';
const [state, formAction] = useFormState(action, initialState);

// React 19
import { useActionState } from 'react';
const [state, formAction, isPending] = useActionState(action, initialState);

Để hiển thị trạng thái chờ trong một nút submit lồng sâu, useFormStatus từ react-dom đọc trạng thái của form cha mà không cần props. Trang tổng quan React 19 liệt kê nó cùng các tính năng form khác.

Lỗi và khi nào nên dùng thứ khác

Nếu action ném lỗi, React hiển thị error boundary gần nhất thay vì cập nhật state. Với những lỗi người dùng có thể tự sửa, như dữ liệu không hợp lệ hay tên người dùng đã có người khác đăng ký, hãy trả chúng về dưới dạng state, như trong ví dụ đăng ký. Còn những sự cố thật thì cứ để chúng ném lỗi.

useActionState dành cho kết quả của một action. Với giá trị cần cập nhật ngay lập tức trong lúc action chạy, như số lượt thích phải tăng ngay khi click, hãy kết hợp nó với useOptimistic. Với ô nhập thay đổi theo từng phím gõ và được đọc trong lúc render, useState thông thường và một controlled input vẫn là công cụ phù hợp.

Lỗi thường gặp

Quên tham số state trước đó. async function save(formData) nhận state trước đó trong formData. Với form, chữ ký hàm luôn là (previousState, formData).

Ô nhập không có name. FormData chỉ chứa các trường có thuộc tính name. Một trường chỉ có id sẽ không có trong formData.get(...), hàm này trả về null.

Dùng controlled input ở mọi nơi. Bạn vẫn có thể dùng value và onChange bên trong form action, nhưng không bắt buộc. Các trường uncontrolled với name và defaultValue hợp với action hơn, và việc React đặt lại form sau khi submit chỉ ảnh hưởng tới các trường uncontrolled.

Đọc state bên trong action. state của component là giá trị từ lần render đã tạo ra handler. Bên trong action, hãy dùng previousState, luôn là kết quả của lời gọi ngay trước đó, kể cả khi nhiều lời gọi đang xếp hàng.

Ném lỗi cho những lỗi có thể đoán trước. Một lỗi bị ném sẽ thay form bằng error boundary gần nhất. Sai mật khẩu không phải là sự cố sập ứng dụng; hãy trả nó về dưới dạng state.