Hook useActionState di React: Formulir, Error, dan Pending

useActionState adalah hook React 19 yang menjalankan fungsi async (sebuah action), menyimpan apa pun yang dikembalikannya sebagai state, dan memberi tahu apakah action itu masih berjalan. Kamu memanggilnya sebagai const [state, formAction, isPending] = useActionState(action, initialState) lalu memberikan formAction ke <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>
    );
}

Kirim formulir kosong dulu: action mengembalikan object error dan pesannya muncul. Lalu ketik alamat yang berisi @ dan kirim lagi. Selama satu detik, tombolnya bertuliskan "Subscribing..." dan dinonaktifkan.

Sintaksnya

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

• action adalah fungsi yang dijalankan. React memanggilnya sebagai action(previousState, ...args). Apa pun yang dikembalikannya (atau hasil resolve-nya, kalau async) menjadi state yang baru.
• initialState adalah state sebelum action pernah berjalan. Pakai bentuk yang sama dengan yang dikembalikan action, agar komponen juga bisa membaca state.message di render pertama.
• state adalah hasil terbaru.
• formAction adalah versi action-mu yang sudah dibungkus. Berikan ke <form action> atau <button formAction>, atau panggil sendiri.
• isPending bernilai true sejak action dimulai sampai selesai.
• permalink bersifat opsional dan hanya penting untuk Server Function di sebuah framework: URL yang harus dituju formulir kalau dikirim sebelum JavaScript selesai dimuat.

Action menerima state sebelumnya sebagai argumen pertama. Ini kesalahan paling umum saat memindahkan sebuah formulir: menulis async function save(formData) membuatmu mendapatkan state lama di formData, dan formData.get melempar error.

Membaca formulir dengan FormData

Saat formAction dipakai sebagai action sebuah formulir, React memanggil action-mu dengan FormData dari formulir itu. Setiap field yang punya name ada di dalamnya. Kamu tidak butuh useState untuk input-nya atau handler onChange, dan kamu tidak memanggil e.preventDefault(): React yang menangani event 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>
    );
}

Hilangkan centang Spicy lalu kirim lagi: key spicy hilang dari data yang dicatat, karena checkbox yang tidak dicentang tidak mengirim apa pun. Action ini juga membaca previousState.count untuk menambahkan satu, itulah sebabnya state sebelumnya datang lebih dulu.

Mengembalikan error validasi

Validasi tempatnya di dalam action. Kembalikan error sebagai bagian dari state, dan kembalikan nilai yang diketik pengguna agar formulir bisa memasangnya lagi. Setelah form action selesai, React mereset field uncontrolled di formulir, jadi field tanpa defaultValue={state.values...} akan kembali kosong setelah submit yang gagal.

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>
    );
}

Ketik nama satu huruf dan password yang pendek, lalu kirim. Kedua error muncul dan kedua field tetap berisi apa yang kamu ketik. Hapus defaultValue={state.values.name} lalu kirim lagi: field nama mengosongkan dirinya setelah error.

Di aplikasi sungguhan, jadikan server sebagai penentu akhir. Pengecekan di client memberi umpan balik cepat, tapi siapa pun bisa mengirim request tanpa melewati formulirmu.

Memanggil action di luar formulir

formAction adalah fungsi, jadi tombol atau effect juga bisa memanggilnya. Saat kamu memanggilnya sendiri, bungkus pemanggilannya di startTransition. Formulir melakukannya untukmu; onClick biasa tidak, dan tanpa transition isPending tidak diperbarui dengan benar (React mencatat error tentang hal itu di 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>
    );
}

Klik Load more beberapa kali. Setiap pemanggilan dimulai dari state yang dikembalikan pemanggilan sebelumnya, jadi halaman-halaman ditambahkan secara berurutan. Kalau kamu memanggil action lagi selagi masih berjalan, React mengantrekan pemanggilan itu dan menjalankannya setelah yang sekarang selesai, masing-masing dengan state terbaru.

Asal-usul useActionState

Sebelum React 19 dirilis, hook ini tersedia di build canary sebagai useFormState, yang di-import dari react-dom. Namanya lalu diganti menjadi useActionState, dipindahkan ke react, dan diberi nilai isPending. Kalau kamu menemukan kode lama seperti ini, perbaikannya ada di import dan namanya:

// 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);

Untuk menampilkan state pending di tombol submit yang bersarang dalam, useFormStatus dari react-dom membaca status formulir induknya tanpa props. Ringkasan React 19 mencantumkannya bersama fitur formulir lainnya.

Error dan kapan memakai cara lain

Kalau action melempar error, React menampilkan error boundary terdekat alih-alih memperbarui state. Untuk error yang bisa diperbaiki pengguna, seperti validasi atau username yang sudah dipakai, kembalikan sebagai state, seperti di contoh pendaftaran. Biarkan kegagalan yang sungguhan melempar error.

useActionState dipakai untuk hasil dari sebuah action. Untuk nilai yang langsung diperbarui selama action berjalan, seperti jumlah like yang harus naik saat diklik, gabungkan dengan useOptimistic. Untuk input yang berubah di setiap ketukan tombol dan dibaca saat render, useState biasa dan controlled input tetap menjadi alat yang tepat.

Kesalahan umum

Lupa parameter state sebelumnya. async function save(formData) menerima state sebelumnya di formData. Untuk formulir, signature-nya selalu (previousState, formData).

Input tanpa name. FormData hanya berisi field yang punya atribut name. Field yang hanya punya id tidak ada di formData.get(...), yang mengembalikan null.

Controlled input di mana-mana. Kamu tetap bisa memakai value dan onChange di dalam form action, tapi tidak wajib. Field uncontrolled dengan name dan defaultValue lebih cocok untuk action, dan reset yang dilakukan React setelah submit hanya memengaruhi field uncontrolled.

Membaca state di dalam action. state dari komponen adalah nilai dari render yang membuat handler tersebut. Di dalam action, pakai previousState, yang selalu berisi hasil pemanggilan sebelumnya, bahkan saat beberapa pemanggilan sedang diantrekan.

Melempar error untuk kesalahan yang sudah diperkirakan. Error yang dilempar akan mengganti formulir dengan error boundary terdekat. Password yang salah bukanlah crash; kembalikan sebagai state.