forwardRef React: Mengirim Ref, dan Ref sebagai Prop di 19

forwardRef memungkinkan komponen induk mengirim ref melewati komponenmu ke elemen DOM di dalamnya, sehingga induk bisa memanggil focus(), scrollIntoView(), dan method serupa pada elemen itu. Di React 19, kamu tidak lagi membutuhkannya: function component menerima ref sebagai prop biasa. forwardRef masih berjalan, dan kamu akan menemuinya di sebagian besar kode yang sudah ada, jadi halaman ini menunjukkan keduanya.

import { forwardRef, useRef } from 'react';

const FancyInput = forwardRef(function FancyInput(props, ref) {
    return <input ref={ref} {...props} style={{ padding: 6, border: '2px solid #6c5ce7' }} />;
});

export default function App() {
    const inputRef = useRef(null);

    function handleClick() {
        inputRef.current.focus();
        console.log('the ref points to an', inputRef.current.tagName);
    }

    return (
        <div>
            <FancyInput ref={inputRef} placeholder="Name" />{' '}
            <button onClick={handleClick}>Focus</button>
        </div>
    );
}

forwardRef menerima fungsi render dengan dua argumen: props, dan ref yang dikirim induk. ref tidak berada di dalam props; ia datang tersendiri. Klik Focus, dan konsol memastikan bahwa inputRef.current adalah node <input> yang sesungguhnya.

Cara React 19: ref adalah prop

Sejak React 19, function component mendapat ref di props-nya seperti prop lain. Tanpa wrapper, tanpa argumen kedua:

import { useRef } from 'react';

function FancyInput({ ref, ...props }) {
    return <input ref={ref} {...props} style={{ padding: 6, border: '2px solid #00b894' }} />;
}

export default function App() {
    const inputRef = useRef(null);

    return (
        <div>
            <FancyInput ref={inputRef} placeholder="Email" />{' '}
            <button onClick={() => inputRef.current.focus()}>Focus</button>{' '}
            <button onClick={() => console.log('value:', inputRef.current.value)}>
                Log value
            </button>
        </div>
    );
}

Ketik sesuatu lalu klik Log value: induknya membaca teks terkini input langsung dari node DOM. Hapus ref={ref} dari <input> lalu klik Focus: konsol menampilkan error, karena inputRef.current sekarang bernilai null.

Ref yang diabaikan anak tetap null

Mengirim ref ke sebuah komponen tidak melakukan apa pun dengan sendirinya. Komponen itu harus memasangnya ke sebuah elemen. Jika tidak, ref.current tetap null:

import { useRef } from 'react';

function Forgetful({ placeholder }) {
    return <input placeholder={placeholder} />;
}

function Careful({ ref, placeholder }) {
    return <input ref={ref} placeholder={placeholder} />;
}

export default function App() {
    const a = useRef(null);
    const b = useRef(null);

    function check() {
        console.log('Forgetful ref:', a.current);
        console.log('Careful ref:', b.current && b.current.tagName);
    }

    return (
        <div>
            <Forgetful ref={a} placeholder="Forgetful" />{' '}
            <Careful ref={b} placeholder="Careful" />{' '}
            <button onClick={check}>Check refs</button>
        </div>
    );
}

Konsol menampilkan Forgetful ref: null dan Careful ref: INPUT. Inilah alasan paling umum di balik "ref.current is null" pada komponen buatan sendiri. Sebelum React 19, Careful pun akan bernilai null kecuali dibungkus forwardRef, karena ref tidak pernah diserahkan ke fungsinya.

useImperativeHandle: tampilkan API yang lebih kecil

Memberi induk seluruh node DOM berarti induk bisa melakukan apa saja padanya: mengubah gaya, menghapus anak, membaca nilai yang ingin kamu rahasiakan. useImperativeHandle memungkinkanmu menentukan isi ref.current sebagai gantinya:

import { useImperativeHandle, useRef } from 'react';

function SearchBox({ ref }) {
    const inputRef = useRef(null);

    useImperativeHandle(ref, () => ({
        focus() {
            inputRef.current.focus();
        },
        clear() {
            inputRef.current.value = '';
            console.log('cleared by the parent');
        },
    }), []);

    return <input ref={inputRef} placeholder="Search" defaultValue="react hooks" />;
}

export default function App() {
    const searchRef = useRef(null);

    return (
        <div>
            <SearchBox ref={searchRef} />{' '}
            <button onClick={() => searchRef.current.focus()}>Focus</button>{' '}
            <button onClick={() => searchRef.current.clear()}>Clear</button>{' '}
            <button onClick={() => console.log('the parent sees:', Object.keys(searchRef.current))}>
                What can the parent see?
            </button>
        </div>
    );
}

Tombol terakhir mencatat ["focus", "clear"]: induk mendapat dua method itu dan tidak ada yang lain, bukan node input-nya. Tambahkan method select() ke objek itu dan sebuah tombol yang memanggilnya, dan induk mendapat tepat satu kemampuan tambahan.

Komponen anak menyimpan ref-nya sendiri, inputRef, untuk input yang sesungguhnya, dan handle membungkusnya. Argumen ketiga adalah array dependensi, seperti milik useEffect: handle dibuat ulang saat nilai-nilai itu berubah.

Pakai ini secukupnya. Sebagian besar yang diinginkan induk (membuka, menutup, menampilkan error) lebih baik dijadikan props, seperti isOpen atau error. Method imperatif cocok untuk aksi yang tidak punya prop alami: memberi fokus, scroll, memutar video, memulai animasi.

Memakai ref di dalam anak juga

Kadang komponen anak butuh node DOM yang sama untuk keperluannya sendiri, misalnya untuk mengukurnya atau memberinya fokus setelah error, sementara induk juga memegang ref ke node itu. Satu atribut ref hanya bisa menerima satu nilai, jadi gabungkan keduanya dengan ref callback:

function AutoGrowTextarea({ ref, ...props }) {
    const localRef = useRef(null);

    function setRefs(node) {
        localRef.current = node;
        if (typeof ref === 'function') ref(node);
        else if (ref) ref.current = node;
    }

    return <textarea ref={setRefs} {...props} />;
}

ref milik induk bisa berupa objek dari useRef atau sebuah fungsi, jadi tangani keduanya. Saat induk hanya butuh beberapa aksi, useImperativeHandle di atas adalah pilihan yang lebih rapi, karena komponen anak menyimpan node itu untuk dirinya sendiri.

Mengirim ref melewati beberapa lapisan

Ref berpindah satu komponen demi satu komponen. Jika Form merender Field, yang merender TextInput, yang merender <input>, setiap komponen itu harus meneruskan ref ke komponen berikutnya. Di React 19, itu hanya satu prop tambahan untuk diteruskan (<TextInput ref={ref} />); dengan forwardRef, setiap lapisan harus dibungkus. Spread props ({...props}) tidak membawanya di versi lama, karena sebelum React 19 ref tidak pernah menjadi bagian dari props.

Komponen design system adalah tempat yang biasanya membuat hal ini penting: Button, Input, atau Select yang membungkus elemen bawaan sebaiknya meneruskan ref-nya, agar aplikasi yang memakainya bisa memberinya fokus, mengukurnya, atau menyerahkannya ke library yang mengatur posisi popover.

Migrasi dari forwardRef

Perubahannya mekanis: hapus wrapper-nya dan baca ref dari props.

// Before
const Button = forwardRef(function Button({ variant, ...props }, ref) {
    return <button ref={ref} className={variant} {...props} />;
});

// After (React 19)
function Button({ variant, ref, ...props }) {
    return <button ref={ref} className={variant} {...props} />;
}

Tidak perlu terburu-buru. forwardRef tetap berjalan di React 19, dan library yang harus mendukung React 18 perlu mempertahankannya, karena React 18 tidak mengirim ref sebagai prop. Class component tidak terpengaruh: ref pada class component tetap menunjuk ke instance komponen.

TypeScript

Dengan forwardRef, argumen tipenya datang dengan urutan tipe ref, lalu props:

import { forwardRef } from 'react';

type FancyInputProps = { label: string };

const FancyInput = forwardRef<HTMLInputElement, FancyInputProps>(
    function FancyInput({ label }, ref) {
        return <input ref={ref} aria-label={label} />;
    }
);

Di React 19, beri tipe pada ref seperti prop lain. ComponentProps<'input'> sudah mencakupnya:

import { useImperativeHandle, useRef, type ComponentProps, type Ref } from 'react';

function FancyInput(props: ComponentProps<'input'>) {
    return <input {...props} />;
}

type SearchHandle = { focus: () => void; clear: () => void };

function SearchBox({ ref }: { ref?: Ref<SearchHandle> }) {
    const inputRef = useRef<HTMLInputElement>(null);
    useImperativeHandle(ref, () => ({
        focus: () => inputRef.current?.focus(),
        clear: () => {
            if (inputRef.current) inputRef.current.value = '';
        },
    }));
    return <input ref={inputRef} />;
}

// In the parent
const searchRef = useRef<SearchHandle>(null);

Halaman useRef membahas ref itu sendiri: akses DOM, nilai yang bertahan tanpa memicu render, dan ref callback. Untuk memberi tipe pada komponen secara umum, lihat React dengan TypeScript.