API Referansı
Hook'lar

useImperativeHandle

useImperativeHandle, bir ref olarak açığa çıkarılan tanımlayıcıyı özelleştirmenizi sağlayan bir React Hook’udur.

useImperativeHandle(ref, createHandle, dependencies?)

Başvuru dokümanı

useImperativeHandle(ref, createHandle, dependencies?)

Açığa çıkarılan ref tanımlayıcısını özelleştirmek için bileşeninizin üst düzeyinde useImperativeHandle’ı çağırın:

import { useImperativeHandle } from 'react';

function MyInput({ ref }) {
  useImperativeHandle(ref, () => {
    return {
      // ... metotlarınız ...
    };
  }, []);
  // ...

Daha fazla örnek için aşağıya bakınız.

Parametreler

  • ref: MyInput bileşenine prop olarak aldığınız ref.

  • createHandle: Herhangi bir argüman almayan ve açığa çıkarmak istediğiniz ref tanımlayıcısını döndüren bir fonksiyondur. Bu ref tanımlayıcısı herhangi bir tipte olabilir. Genellikle, açığa çıkarmak istediğiniz metotların bulunduğu bir nesne döndürürsünüz.

  • isteğe bağlı dependencies: createHandle kodu içinde referans alınan tüm tepkisel değerlerin listesidir. Tepkisel değerler, prop’lar, state ve bileşeninizin doğrudan içerisinde bildirilen tüm değişkenler ve fonskiyonlar gibi değerleri içerir. Eğer linter’ınız React için yapılandırılmışsa, her tepkisel değerin doğru bir şekilde bağımlılık(dependency) olarak belirtildiğini doğrular. Bağımlılık listesi, sabit bir sayıda öğeye sahip olmalı ve [dep1, dep2, dep3] gibi iç içe yazılmalıdır. React, her bir bağımlılığı önceki değeriyle Object.is karşılaştırması kullanarak karşılaştırır. Eğer bir yeniden render’lama, bazı bağımlılıklarda değişikliğe neden olduysa veya bu argümanı atladıysanız, createHandle fonksiyonunuz yeniden çalıştırılır ve yeni oluşturulan tanımlayıcı ref’e atanır.

Not

React 19 ile birlikte, ref bir prop olarak mevcuttur. React 18 ve öncesinde, ref’i forwardRef’den almak gerekiyordu.

Returns

useImperativeHandle, undefined döndürür.

Kullanım

Özel bir ref tanımlayıcısını üst elemana açığa çıkarma

Bir DOM düğümünü ebeveyn elemana açığa çıkarmak için, ref prop’unu düğüme iletin.

function MyInput({ ref }) {
  return <input ref={ref} />;
};

Yukarıdaki kodla, MyInput’e ait bir ref, <input> DOM düğümünü alacaktır. Ancak bunun yerine özel bir değer de açığa çıkarabilirsiniz. Açığa çıkan handle’ı özelleştirmek için, bileşeninizin üst seviyesinde useImperativeHandle çağırın:

import { useImperativeHandle } from 'react';

function MyInput({ ref }) {
  useImperativeHandle(ref, () => {
    return {
      // ... metotlarınız ...
    };
  }, []);

  return <input />;
};

Yukarıdaki kodda, ref’in artık <input>’a iletilmediğine dikkat edin.

Örneğin, <input> DOM düğümünün tamamını açığa çıkarmak istemiyorsunuz, ancak focus ve scrollIntoView gibi iki metodu açığa çıkarmak istiyorsunuz. Bunun için gerçek tarayıcı DOM’unu ayrı bir ref içinde tutun. Ardından, yalnızca üst elemanın çağırmasını istediğiniz metotlara sahip bir tanımlayıcıyı açığa çıkarmak için useImperativeHandle’ı kullanın:

import { useRef, useImperativeHandle } from 'react';

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

  useImperativeHandle(ref, () => {
    return {
      focus() {
        inputRef.current.focus();
      },
      scrollIntoView() {
        inputRef.current.scrollIntoView();
      },
    };
  }, []);

  return <input ref={inputRef} />;
};

Artık, eğer üst eleman MyInput için bir ref alırsa, onun üzerinde focus ve scrollIntoView metotlarını çağırabilecektir. Ancak, altında bulunan <input> DOM düğümüne tam erişimi olmayacaktır.

import { useRef } from 'react';
import MyInput from './MyInput.js';

export default function Form() {
  const ref = useRef(null);

  function handleClick() {
    ref.current.focus();
    // DOM düğümü açığa çıkarılmadığı için bu çalışmayacaktır:
    // ref.current.style.opacity = 0.5;
  }

  return (
    <form>
      <MyInput placeholder="Adınızı girin" ref={ref} />
      <button type="button" onClick={handleClick}>
        Düzenle
      </button>
    </form>
  );
}

Zorunlu fonksiyonlarızı açığa çıkarma

İstemci tarafından kullanılabilir hâle getirdiğiniz metotlar, DOM metotlarıyla tam olarak eşleşmek zorunda değildir. Örneğin, bu Post bileşeni, bir istemci tarafından kullanılabilir hâle getirilen scrollAndFocusAddComment metodunu açığa çıkarır. Bu, üst eleman olan Page’in, butona tıklandığında yorum listesine kaydırmasına ve giriş alanına odaklanmasına olanak tanır:

import { useRef } from 'react';
import Post from './Post.js';

export default function Page() {
  const postRef = useRef(null);

  function handleClick() {
    postRef.current.scrollAndFocusAddComment();
  }

  return (
    <>
      <button onClick={handleClick}>
        Bir yorum yazın
      </button>
      <Post ref={postRef} />
    </>
  );
}

Tuzak

Ref’leri aşırı kullanmayın. Ref’leri sadece, prop olarak ifade edemeyeceğiniz zorunlu davranışlar için kullanmalısınız: örneğin, bir düğüme kaydırmak, bir düğüme odaklanmak, bir animasyonu tetiklemek, metin seçmek vb.

Bir şeyi bir prop olarak ifade edebiliyorsanız, bir ref kullanmamalısınız. Örneğin, bir Modal bileşeninden { open, close } gibi bir ref açığa çıkarmak yerine, <Modal isOpen={isOpen} /> gibi bir isOpen prop’unu almak daha iyidir. Effect’ler, ref’leri prop’lar aracılığıyla açığa çıkarmada size yardımcı olabilir.

ÖncekiuseId
SonrakiuseInsertionEffect