Membangun Optimistic UI di React dengan TanStack Query: Mutasi Cepat dan Rollback Otomatis
Batas Persepsi Pengguna dan Alasan Optimistic UI Dibutuhkan
Interaksi terasa instan bagi pengguna pada rentang sekitar 100 ms. Sebagian besar request jaringan di aplikasi React memakan waktu 200–800 ms, dan angka itu membengkak pada koneksi seluler yang tidak stabil. Selisih antara ambang persepsi dan latensi nyata inilah yang membuat tombol terasa berat, meski server sebenarnya bekerja dengan benar.
Di titik ini perceived performance dan actual performance berpisah. Actual performance diukur dari waktu server menyelesaikan pekerjaan. Perceived performance diukur dari seberapa cepat pengguna melihat reaksi di layar. Optimistic UI memperbaiki sisi kedua tanpa mengubah sisi pertama. Antarmuka menampilkan hasil mutasi seolah request sudah berhasil, sebelum server mengonfirmasi apa pun.
Konsekuensinya harus diterima sejak awal. Data sementara di cache bisa saja salah, dan tampilan wajib bisa dikembalikan ke kondisi sebelumnya saat request gagal. Pendekatan ini tepat untuk operasi yang murah dibatalkan dan sering dipicu pengguna, seperti like, toggle, reorder, dan komentar. Pendekatan ini tidak tepat untuk pembayaran, pemotongan saldo, atau pembelian stok terbatas, karena kesalahan sementara di area tersebut berubah menjadi masalah nyata.
Risiko terbesar muncul saat optimisme diterapkan tanpa mekanisme rollback. Pengguna melihat item bertambah, lalu item itu menghilang setelah beberapa detik tanpa penjelasan. Kepercayaan pada aplikasi turun lebih cepat daripada manfaat kecepatan yang didapat.
Peran Cache TanStack Query sebagai Sumber Kebenaran Sementara
QueryClient menyimpan hasil request berdasarkan queryKey. Setiap daftar todo, profil pengguna, atau detail produk memiliki entri cache sendiri. Komponen yang memanggil useQuery membaca dari entri tersebut, bukan menyimpan salinan terpisah di useState.
Karena itu, optimistic update ditulis ke cache, bukan ke state lokal komponen. Cache adalah salinan data server di memori browser, dan semua komponen yang membaca queryKey yang sama akan langsung melihat perubahan. Menulis ke useState hanya memperbarui satu komponen, sementara komponen lain tetap menampilkan data lama sampai refetch selesai.

Gambar: Cache QueryClient menjadi satu sumber data untuk seluruh komponen — Sumber: Rumah Coding (diagram dibuat sendiri)
Dalam satu siklus data, useQuery membaca cache, useMutation mengubahnya, lalu TanStack Query menyinkronkan hasil akhir dengan server. Dua opsi konfigurasi mengatur umur data. staleTime menentukan berapa lama data dianggap segar sehingga tidak di-refetch. gcTime menentukan berapa lama entri yang tidak dipakai bertahan di memori sebelum dibuang.
Sebelum menulis ke cache, kita memanggil queryClient.cancelQueries. Langkah ini menghentikan refetch yang sedang berjalan agar respons lama tidak menimpa perubahan optimistik yang baru saja ditulis. Siklus mutasi berjalan berurutan: onMutate → request → onError atau onSuccess → onSettled. Setiap tahap punya peran yang jelas, dan rollback bergantung pada urutan tersebut.

Gambar: Siklus optimistic update dan jalur rollback pada TanStack Query — Sumber: Rumah Coding (diagram dibuat sendiri)
Menulis Perubahan ke Cache di Dalam onMutate
Fullstack Web Development With Next.js
A practical, beginner-friendly, and project-based introduction to full-stack web...
useMutation menerima mutationFn yang memanggil API dan onMutate yang dijalankan sebelum request dikirim. Di dalam onMutate, kita menjalankan tiga operasi dengan urutan tetap: batalkan refetch, ambil snapshot, lalu tulis data baru.
// npm install @tanstack/react-query
import { useMutation, useQueryClient } from '@tanstack/react-query';
type Todo = { id: string; title: string; completed: boolean };
async function createTodo(title: string): Promise<Todo> {
const response = await fetch('/api/todos', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ title }),
});
if (!response.ok) {
throw new Error('Gagal menyimpan todo');
}
return response.json();
}
export function useCreateTodo() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: createTodo,
onMutate: async (title) => {
await queryClient.cancelQueries({ queryKey: ['todos'] });
const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
const optimisticTodo: Todo = {
id: `temp-${crypto.randomUUID()}`,
title,
completed: false,
};
queryClient.setQueryData<Todo[]>(['todos'], (old = []) => [
...old,
optimisticTodo,
]);
return { previousTodos };
},
});
}Snapshot diambil lewat getQueryData dan dikembalikan sebagai context. Nilai ini menjadi pegangan saat request gagal. Setelah snapshot aman, setQueryData menulis item baru dengan ID sementara. Komponen yang membaca ['todos'] langsung menerima daftar terbaru pada render berikutnya, tanpa menunggu isPending berubah menjadi false.
Satu kesalahan umum muncul di sini. Banyak developer memutasi array hasil getQueryData secara langsung dengan push, lalu menganggap snapshot sudah tersimpan. Snapshot tersebut menunjuk ke objek yang sama, sehingga perubahan ikut merusak data lama dan rollback tidak lagi mengembalikan apa pun. Selalu buat array baru dengan spread operator atau map.
Hasil yang diharapkan sederhana: todo baru muncul di daftar segera setelah tombol ditekan, sementara request masih berjalan di tab Network. Tidak ada spinner yang menahan seluruh halaman, dan pengguna bisa melanjutkan aktivitas lain.
Mengembalikan State Lama Saat Request Gagal
onError menerima tiga argumen: error, variabel mutasi, dan context. Parameter ketiga inilah sumber snapshot. Rollback dilakukan dengan satu panggilan setQueryData yang mengembalikan nilai lama.
export function useCreateTodo() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: createTodo,
retry: 2,
onMutate: async (title) => {
await queryClient.cancelQueries({ queryKey: ['todos'] });
const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
queryClient.setQueryData<Todo[]>(['todos'], (old = []) => [
...old,
{ id: `temp-${crypto.randomUUID()}`, title, completed: false },
]);
return { previousTodos };
},
onError: (error, _title, context) => {
if (context?.previousTodos) {
queryClient.setQueryData(['todos'], context.previousTodos);
}
console.error('Mutasi gagal:', error.message);
},
onSettled: async () => {
await queryClient.invalidateQueries({ queryKey: ['todos'] });
},
});
}Penulisan ulang cache harus disertai pesan yang jelas. Tampilkan notifikasi bahwa penyimpanan gagal, dan jangan hapus input pengguna. Menghapus input memaksa pengguna mengetik ulang dan menambah frustrasi. Pertahankan teks di form, beri tanda gagal, lalu sediakan tombol coba lagi.
onSettled dijalankan setelah sukses maupun gagal. Tempat ini paling tepat untuk invalidateQueries, karena invalidasi menandai cache sebagai usang dan memicu refetch dari server. Dengan begitu, data akhir tetap sesuai kebenaran server, bukan sesuai tebakan client.
Rollback tidak boleh bergantung pada refetch saja. Refetch bisa lambat, dan pada kondisi jaringan buruk refetch juga bisa gagal. Snapshot lokal memberi jaminan langsung, sedangkan refetch hanya menyempurnakan hasil akhir. Opsi retry terbatas pada mutasi membantu melewati gangguan jaringan sesaat tanpa langsung membatalkan tampilan. Dua kali percobaan biasanya cukup, dan angka yang terlalu besar membuat pengguna menunggu tanpa kepastian.
Menangani Mutasi Beruntun, ID Sementara, dan Konflik Data
Pengguna sering menekan tombol beberapa kali sebelum respons pertama tiba. Tanpa pengaman, setiap tekanan mengirim request baru dan setiap onMutate menimpa snapshot sebelumnya. Hasilnya bisa berupa duplikasi item atau rollback yang mengembalikan state yang salah.
cancelQueries dengan queryKey spesifik membantu mencegah refetch menimpa perubahan optimistik. Untuk mutasi per item, gunakan mutationKey yang memuat ID item sehingga status tiap mutasi bisa dilacak terpisah. Nonaktifkan tombol memakai isPending milik mutasi item tersebut, bukan status global yang memblokir seluruh halaman.
export function TodoItem({ todo }: { todo: Todo }) {
const queryClient = useQueryClient();
const { mutate, isPending } = useMutation({
mutationKey: ['toggle-todo', todo.id],
mutationFn: async (next: Todo) => {
const response = await fetch(`/api/todos/${next.id}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ completed: next.completed }),
});
if (!response.ok) {
throw new Error('Gagal memperbarui todo');
}
return response.json() as Promise<Todo>;
},
onMutate: async (next) => {
await queryClient.cancelQueries({ queryKey: ['todos'] });
const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
queryClient.setQueryData<Todo[]>(['todos'], (old = []) =>
old.map((item) => (item.id === next.id ? next : item)),
);
return { previousTodos };
},
onError: (_error, _next, context) => {
queryClient.setQueryData(['todos'], context?.previousTodos);
},
onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
});
return (
<button
onClick={() => mutate({ ...todo, completed: !todo.completed })}
disabled={isPending}
>
{todo.completed ? 'Tandai belum selesai' : 'Tandai selesai'}
</button>
);
}ID sementara dibuat di client agar item bisa langsung dirender dan dipilih. Setelah server merespons, ganti ID sementara dengan ID asli melalui onSuccess atau biarkan onSettled menyegarkan daftar dari server. Pendekatan kedua lebih sederhana dan lebih aman untuk data yang punya relasi.
Pada setiap mutasi, onMutate harus mengembalikan snapshot terbaru. Snapshot lama dari mutasi sebelumnya tidak lagi mewakili kondisi cache saat ini.
Optimistic UI punya batas yang jelas. Operasi yang bergantung pada nilai otoritatif dari server, seperti stok, saldo, atau kuota, tidak cocok ditampilkan seolah berhasil. Untuk kebutuhan tersebut, gunakan useMutationState guna menampilkan status per mutasi tanpa mengubah data utama.
Menguji, Memantau, dan Menjaga Optimistic UI Tetap Sehat
Pengujian dimulai dari skenario gagal. Matikan koneksi jaringan, lalu tekan tombol. Pastikan item optimistik hilang dan data lama kembali. Ulangi dengan mock server yang mengembalikan error 500 untuk memastikan onError berjalan pada jalur yang sama.
React Query Devtools membantu memeriksa isi cache sebelum dan sesudah mutasi. Log di onError menampilkan error, variabel mutasi, dan snapshot yang dipakai untuk rollback. Keduanya cukup untuk melacak sebagian besar bug optimistik.
Metrik yang perlu diamati mencakup waktu render setelah mutasi, jumlah request ganda per aksi, dan tingkat kegagalan mutasi. Lonjakan request ganda biasanya menandakan tombol tidak dinonaktifkan dengan benar. Tingkat kegagalan yang tinggi menandakan optimistic UI sedang menutupi masalah backend.
Jaga konsistensi dengan satu pola rollback untuk seluruh aplikasi. Selalu clone snapshot sebelum menulis ke cache. Sebelum rilis, pastikan request punya timeout, kondisi offline ditangani, dan pesan error bisa ditindaklanjuti pengguna. Jika sebuah operasi sering gagal atau melibatkan nilai yang tidak boleh salah, kembalilah ke mutasi biasa tanpa optimisme.
Optimistic UI yang baik bukan sekadar animasi cepat. Di baliknya ada pemahaman cache, siklus mutasi, dan strategi rollback yang rapi. Materi React dan manajemen state server dibahas langsung dalam konteks aplikasi produksi di Rumah Coding, mulai dari data fetching sampai penanganan kegagalan. Bergabunglah dengan program Web Development untuk membangun kebiasaan teknis yang siap dipakai di proyek nyata.
Kursus Terkait
Fullstack Web Development With Next.js
A practical, beginner-friendly, and project-based introduction to full-stack web development. Students will learn to build, secure, and deploy modern web applications from scratch using Next.js (App Router), React, Tailwind CSS, and a relational database. By the end of the course, students will have a fully functional, production-ready application to showcase in their portfolio.
TechConnect - Modern IT Job Portal
- Public Job Board: A responsive homepage displaying available job listings with dynamic routing for individual job detail pages.
- Search & Filter: Basic functionality allowing users to find jobs based on keywords or categories.
- User Authentication: Secure Sign Up, Log In, and Log Out workflows.
MERN Stack Development
Launch your journey into full-stack web development with this comprehensive, project-driven course. Designed for beginners, this course demystifies the MERN stack (MongoDB, Express.js, React.js, Node.js) by guiding you step-by-step in building a real-world application from scratch. By the end of this course, you will have the practical skills and a complete portfolio project to confidently step into the modern web development industry.
EduStream - Mini Learning Management System (LMS)
- Secure Authentication & Authorization: Robust user registration and login using JWT, with strict role-based access control (Admin/Instructor vs. Student).
- Course Management (Admin Dashboard): Full CRUD (Create, Read, Update, Delete) capabilities for administrators to manage course details, including titles, descriptions, pricing, and thumbnail image uploads.
- Public Course Catalog: An interactive and responsive storefront where users can browse available courses.