React useLayoutEffect: Mengukur Sebelum Browser Menggambar

useLayoutEffect adalah versi useEffect yang berjalan lebih awal: tepat setelah React memperbarui DOM, tapi sebelum browser menggambar frame baru. Kode di dalamnya bisa mengukur elemen dan mengubah layout, dan pengguna hanya melihat hasil akhirnya. Hook ini memblokir proses menggambar selama berjalan, jadi pakai hanya saat kamu butuh waktu yang tepat seperti itu.

import { useState, useEffect, useLayoutEffect } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    console.log('1. render');

    useEffect(() => {
        console.log('3. effect (usually after paint)');
    });

    useLayoutEffect(() => {
        console.log('2. layout effect (before paint)');
    });

    return <button onClick={() => setCount(count + 1)}>Rendered with {count}</button>;
}

Effect-effect itu dideklarasikan dengan urutan effect, lalu layout effect, tapi console mencetak layout effect lebih dulu di setiap render. Urutan deklarasi tidak berpengaruh di antara kedua hook ini; yang berpengaruh adalah waktunya.

Sintaksnya

Signature-nya identik dengan useEffect: fungsi setup, cleanup opsional, dan array dependensi.

useLayoutEffect(() => {
    // runs after the DOM update, before paint
    return () => {
        // cleanup, before the next run and on unmount
    };
}, [dependencies]);

Semua yang kamu ketahui tentang dependensi dan cleanup dari useEffect tetap berlaku. Satu-satunya perbedaan adalah kapan React memanggilnya.

Kapan masing-masing berjalan

Setelah render, React memperbarui DOM lalu melakukan tiga hal dengan urutan tetap:

1. Menjalankan semua cleanup layout effect dan layout effect, secara sinkron.
2. Membiarkan browser menggambar layar. Kalau sebuah layout effect mengatur state, React merender lagi lebih dulu, tetap sebelum paint.
3. Menjalankan effect biasa, biasanya setelah paint.

Di seluruh pohon, setiap layout effect berjalan sebelum effect biasa mana pun, dan child berjalan sebelum parent-nya, karena parent baru bisa selesai setelah child-nya berada di tempatnya:

import { useEffect, useLayoutEffect, useState } from 'react';

function Child() {
    useLayoutEffect(() => {
        console.log('Child layout effect');
    });
    useEffect(() => {
        console.log('Child effect');
    });
    return <p>Child</p>;
}

function Parent() {
    useLayoutEffect(() => {
        console.log('Parent layout effect');
    });
    useEffect(() => {
        console.log('Parent effect');
    });
    return <Child />;
}

export default function App() {
    const [n, setN] = useState(0);
    return (
        <div>
            <button onClick={() => setN(n + 1)}>Render again ({n})</button>
            <Parent key={n} />
        </div>
    );
}

Console menampilkan kedua layout effect lebih dulu, Child lalu Parent, kemudian kedua effect biasa dengan urutan yang sama. key={n} membuat setiap klik me-mount Parent yang baru, jadi kamu mendapat empat baris yang sama setiap kali. Tambahkan cleanup yang mencatat log ke setiap effect dan lihat yang lama berjalan sebelum yang baru.

Masalah kedipan

Bayangkan tooltip yang harus muncul di atas tombolnya, kecuali tidak ada ruang di atas, maka tooltip itu muncul di bawah. Kamu tidak bisa tahu apakah ada ruang sampai tooltip berada di DOM dan tingginya bisa diukur. Jadi rendering terjadi dalam dua tahap:

1. Render tooltip di suatu tempat, agar bisa diukur.
2. Ukur, hitung posisi sebenarnya, atur state, render lagi.

Dengan useEffect, browser mungkin menggambar layar di antara kedua tahap itu, dan pengguna melihat tooltip melompat dari posisi pertama ke posisi kedua. Dengan useLayoutEffect, tahap kedua terjadi sebelum paint, jadi posisi pertama tidak pernah ditampilkan.

import { useLayoutEffect, useRef, useState } from 'react';

function Tooltip({ anchor, text }) {
    const ref = useRef(null);
    const [top, setTop] = useState(0);

    useLayoutEffect(() => {
        const height = ref.current.offsetHeight;
        const above = anchor.offsetTop - height - 6;
        const fits = above >= 0;
        console.log(fits ? 'room above: placing above' : 'no room above: placing below');
        setTop(fits ? above : anchor.offsetTop + anchor.offsetHeight + 6);
    }, [anchor]);

    const style = {
        position: 'absolute', top, left: anchor.offsetLeft,
        background: '#222', color: '#fff', padding: '4px 8px', borderRadius: 4, fontSize: 13,
    };
    return <div ref={ref} style={style}>{text}</div>;
}

export default function App() {
    const [anchor, setAnchor] = useState(null);
    const show = (e) => setAnchor(e.currentTarget);
    const hide = () => setAnchor(null);

    return (
        <div style={{ position: 'relative', height: 160 }}>
            <button onMouseEnter={show} onMouseLeave={hide} style={{ position: 'absolute', top: 0 }}>
                Hover me (top)
            </button>
            <button onMouseEnter={show} onMouseLeave={hide} style={{ position: 'absolute', top: 110 }}>
                Hover me (lower)
            </button>
            {anchor && <Tooltip anchor={anchor} text="A tooltip that picks its side" />}
        </div>
    );
}

Arahkan kursor ke tombol atas: tidak ada ruang di atasnya, jadi tooltip muncul di bawah. Arahkan ke tombol yang lebih bawah dan tooltip muncul di atas. Console memberi tahu sisi mana yang dipilih dari hasil pengukuran. Ganti useLayoutEffect menjadi useEffect lalu arahkan kursor lagi: tooltip sekarang bisa berkedip di bagian atas kotak selama satu frame sebelum berpindah. Di mesin yang cepat, kedipan itu sering terlalu cepat untuk disadari, dan justru itulah sebabnya bug ini sampai dirilis lalu dilaporkan dari ponsel yang lebih lambat.

offsetHeight, offsetTop, dan getBoundingClientRect() semuanya memaksa browser menghitung layout, jadi membacanya di layout effect memberimu nilai sebenarnya dari DOM yang baru saja ditulis React.

Mengukur sebuah elemen

Pola yang sama berlaku untuk ukuran apa pun yang menjadi tumpuan render: baca dengan ref di layout effect, simpan di state, lalu render dengan nilai itu.

import { useLayoutEffect, useRef, useState } from 'react';

export default function App() {
    const [text, setText] = useState('Short');
    const [width, setWidth] = useState(null);
    const boxRef = useRef(null);

    useLayoutEffect(() => {
        const w = Math.round(boxRef.current.getBoundingClientRect().width);
        console.log('measured width for', JSON.stringify(text));
        setWidth(w);
    }, [text]);

    return (
        <div>
            <button onClick={() => setText(text + ' and longer')}>Make it longer</button>
            <p>
                <span ref={boxRef} style={{ background: '#ffeaa7', padding: '2px 6px' }}>
                    {text}
                </span>
            </p>
            <p>The highlighted text is {width} px wide.</p>
        </div>
    );
}

Klik tombolnya dan baris lebar diperbarui dalam frame yang sama dengan teksnya. Halaman tidak pernah menampilkan teks baru di samping lebar lama, karena render kedua terjadi sebelum paint. Hapus [text] dari array dependensi dan pengukuran berjalan setelah setiap render, termasuk render yang dipicu oleh setWidth miliknya sendiri; pengukuran itu berhenti di situ hanya karena lebarnya tidak berubah lagi.

Utamakan useEffect

Layout effect menahan paint sampai selesai, dan kalau mengatur state, sampai render tambahannya juga selesai. Layout effect yang lambat membuat setiap pembaruan di halaman terasa lambat. Pakai useLayoutEffect hanya saat semua hal ini benar:

• Effect itu membaca layout (ukuran, posisi, scroll).
• Effect itu mengubah apa yang dirender berdasarkan bacaan tersebut.
• Keadaan perantaranya akan terlihat dan tampak salah.

Semua hal lain (fetch, subscription, timer, logging, analytics) tempatnya di useEffect. Aturan singkatnya: mulai dengan useEffect, dan ganti hanya kalau kamu bisa melihat kedipan.

useEffect biasanya berjalan setelah paint, tapi tidak selalu. Saat pembaruan datang dari aksi pengguna yang diskret seperti klik atau tekanan tombol, React mungkin menjalankan effect sebelum browser menggambar layar. Itulah salah satu alasan kedipan bisa muncul di satu situasi dan tidak di situasi lain.

Server rendering

Effect tidak pernah berjalan saat server rendering, begitu juga useLayoutEffect. Server mengirim HTML dari render pertama, dan layout effect baru berjalan setelah hidrasi di browser. React 18 dan versi sebelumnya memperingatkan "useLayoutEffect does nothing on the server" saat komponen seperti itu dirender di server; React 19 menghapus peringatan tersebut.

Kalau frame pertama hasil render server akan terlihat salah tanpa pengukuran, ada dua perbaikan yang umum: render fallback yang netral (misalnya, sembunyikan tooltip sampai selesai diukur), atau render komponennya hanya di client:

function ClientOnly({ children }) {
    const [mounted, setMounted] = useState(false);
    useEffect(() => setMounted(true), []);
    return mounted ? children : null;
}

useInsertionEffect

Ada hook effect ketiga, useInsertionEffect, yang berjalan sebelum layout effect mana pun. Hook ini ada untuk library CSS-in-JS yang membuat tag <style> saat runtime: menyisipkan style di sana berarti layout effect yang mengukur sebuah elemen sudah melihatnya dalam keadaan diberi style. Hook ini tidak bisa memperbarui state dan ref belum terpasang, jadi tidak ada gunanya di kode aplikasi. Kalau kamu tidak sedang menulis library styling, kamu tidak akan membutuhkannya.