createRoot React bileşenlerini bir tarayıcı DOM düğümü içinde görüntülemek için bir kök oluşturmanızı sağlar.

const root = createRoot(domNode, options?)

Referans

createRoot(domNode, options?)

İçeriği bir tarayıcı DOM elemanı içinde görüntülemek üzere bir React kökü oluşturmak için createRoot çağrısı yapın.

import { createRoot } from 'react-dom/client';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

React, domNode için bir kök oluşturacak ve içindeki DOM’un yönetimini üstlenecek. Bir kök oluşturduktan sonra, içinde bir React bileşeni görüntülemek için root.render çağırmanız gerekir:

root.render(<App />);

Tamamen React ile oluşturulmuş bir uygulama genellikle kök bileşeni için yalnızca bir createRoot çağrısına sahip olacaktır. Sayfanın bazı bölümleri için React “serpintileri” kullanan bir sayfa, ihtiyaç duyulan kadar çok sayıda ayrı köke sahip olabilir.

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

Parametreler

  • domNode: Bir DOM elemanı. React bu DOM elemanı için bir kök oluşturacak ve render gibi render edilmiş React içeriğini görüntülemek için kök üzerinde fonksiyonlar çağırmanıza izin verecektir.

  • opsiyonel options: Bu React kökü için seçenekler içeren bir nesne.

    • Canary only opsiyonel onCaughtError: React bir Hata yakalayıcı bir hata yakaladığında callback yapılır. Hata yakalayıcı tarafından yakalanan error ve componentStack içeren bir errorInfo nesnesi ile çağrılır.
    • Canary only opsiyonel Bir hata fırlatıldığında ve bir Hata yakalayıcı tarafından yakalanmadığında callback yapılır. Atılan hata ve componentStack’i içeren bir errorInfo nesnesi ile çağrılır.
    • opsiyonel onRecoverableError: React’in hatalardan otomatik olarak kurtulduğunda çağrılan callback fonksiyonu. React’in attığı bir error ve componentStack içeren bir errorInfo nesnesi ile çağrılır. Bazı kurtarılabilir hatalar, error.cause olarak orijinal hata nedenini içerebilir.
    • opsiyonel identifierPrefix: useId tarafından oluşturulan kimlikler için React’in kullandığı bir dize öneki. Aynı sayfada birden fazla kök kullanırken çakışmaları önlemek için kullanışlıdır.

Döndürülenler

createRoot render ve unmount olmak üzere iki yöntem içeren bir nesne döndürür.

Uyarılar

  • Uygulamanız sunucu tarafından oluşturulmuşsa, createRoot() kullanımı desteklenmez. Bunun yerine hydrateRoot() kullanın.
  • Uygulamanızda muhtemelen yalnızca bir createRoot çağrısı olacaktır. Eğer bir çatı kullanıyorsanız, bu çağrıyı sizin için yapabilir.
  • Bileşeninizin alt öğesi olmayan DOM ağacının farklı bir bölümünde bir JSX parçası render etmek istediğinizde (örneğin, bir modal veya bir araç ipucu), createRoot yerine createPortal kullanın.

root.render(reactNode)

React root’un tarayıcı DOM düğümünde bir JSX parçası görüntülemek için root.render çağrısı yapın.

root.render(<App />);

React, root içinde <App /> gösterecek ve içindeki DOM’un yönetimini üstlenecektir.

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

Parametreler

  • reactNode: Görüntülemek istediğiniz bir React düğümü. Bu genellikle <App /> gibi bir JSX parçası olacaktır, ancak createElement() ile oluşturulmuş bir React elemanı, bir string, bir sayı, null veya undefined da iletebilirsiniz.

Döndürülenler

root.render undefined değerini döndürür.

Uyarılar

  • İlk kez root.render fonksiyonunu çağırdığınız zaman React, React bileşenini render etmeden önce React kökü içindeki mevcut tüm HTML içeriğini temizleyecektir.

  • Kök DOM düğümünüz sunucuda veya derleme sırasında React tarafından oluşturulan HTML içeriyorsa, bunun yerine olay işleyicilerini mevcut HTML’ye ekleyen hydrateRoot() fonksiyonunu kullanın.

  • Aynı kök üzerinde birden fazla kez render çağrısı yaparsanız, React ilettiğiniz en son JSX’i yansıtmak için DOM’u gerektiği gibi güncelleyecektir. React, DOM’un hangi bölümlerinin yeniden kullanılabileceğine ve hangilerinin yeniden oluşturulması gerektiğine daha önce oluşturulmuş ağaçla “eşleştirerek” daha önce oluşturulmuş ağaçla karar verecektir. Aynı kök üzerinde render fonksiyonunu tekrar çağırmak, kök bileşen üzerinde set fonksiyonunu çağırmaya benzer: React gereksiz DOM güncellemelerinden kaçınır.

root.unmount()

React kökü içinde render edilmiş bir ağacı yok etmek için root.unmount çağırın.

root.unmount();

Tamamen React ile oluşturulan bir uygulamada genellikle root.unmount çağrısı olmayacaktır.

Bu, çoğunlukla React kök DOM düğümünüzün (veya atalarından herhangi birinin) başka bir kod tarafından DOM’dan kaldırılabileceği durumlarda kullanışlıdır. Örneğin, etkin olmayan sekmeleri DOM’dan kaldıran bir jQuery sekme paneli düşünün. Bir sekme kaldırılırsa, içindeki her şey (içindeki React kökleri de dahil olmak üzere) DOM’dan da kaldırılacaktır. Bu durumda, React’e root.unmount çağrısı yaparak kaldırılan kökün içeriğini yönetmeyi “durdurmasını” söylemeniz gerekir. Aksi takdirde, kaldırılan kökün içindeki bileşenler, abonelikler gibi global kaynakları temizlemeyi ve boşaltmayı bilemez.

root.unmount çağrısı, ağaçtaki tüm olay yöneticilerini veya state’i kaldırmak da dahil olmak üzere, kökteki tüm bileşenleri DOM’dan kaldıracak ve React’i kök DOM düğümünden “ayıracaktır”.

Parametreler

root.unmount herhangi bir parametre kabul etmez.

Döndürülenler

root.unmount undefined döndürür.

Uyarılar

  • root.unmount çağrısı, ağaçtaki tüm bileşenleri DOM’dan kaldıracak ve React’i kök DOM düğümünden “ayıracaktır”.

  • Bir kez root.unmount çağrısı yaptığınızda, aynı kök üzerinde tekrar root.render çağrısı yapamazsınız. Bağlanmamış bir kök üzerinde root.render çağrılmaya çalışıldığında “Bağlanmamış bir kök güncellenemiyor” hatası verilir. Ancak, aynı DOM düğümü için önceki kökün bağlantısı kaldırıldıktan sonra yeni bir kök oluşturabilirsiniz.

Kullanım

Tamamen React ile oluşturulmuş bir uygulamayı render etmek

Eğer uygulamanız tamamen React ile oluşturulmuşsa, uygulamanızın tamamı için tek bir kök oluşturun.

import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

Genellikle bu kodu başlangıçta yalnızca bir kez çalıştırmanız gerekir. Bu işlem şunları yapacaktır:

  1. HTML’nizde tanımlanan tarayıcı DOM düğümünü bulun.
  2. Uygulamanızın React bileşenini içinde görüntüleyin.
import { createRoot } from 'react-dom/client';
import App from './App.js';
import './styles.css';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

Eğer uygulamanız tamamen React ile oluşturulmuşsa, daha fazla kök oluşturmanız veya root.render’ı tekrar çağırmanız gerekmez.

Bu noktadan itibaren React tüm uygulamanızın DOM’unu yönetecektir. Daha fazla bileşen eklemek için, bunları App bileşeninin içine yerleştirin. Kullanıcı arayüzünü güncellemeniz gerektiğinde, bileşenlerinizin her biri bunu state kullanarak yapabilir. DOM düğümünün dışında bir modal veya araç ipucu gibi ekstra içerik görüntülemeniz gerektiğinde, bunu bir portal ile oluşturun.

Not

HTML’niz boş olduğunda, uygulamanın JavaScript kodu yüklenip çalışana kadar kullanıcı boş bir sayfa görür:

<div id="root"></div>

Bu çok yavaş hissettirebilir! Bunu çözmek için, bileşenlerinizden [sunucuda veya derleme sırasında] ilk HTML’yi oluşturabilirsiniz. (/reference/react-dom/server) Ardından ziyaretçileriniz JavaScript kodunun herhangi biri yüklenmeden önce metin okuyabilir, resimleri görebilir ve bağlantılara tıklayabilir. Bu optimizasyonu otomatik olarak yapan bir framework kullanmanızı öneririz. Ne zaman çalıştığına bağlı olarak buna sunucu taraflı render etme (SSR) veya statik site oluşturma (SSG) denir.

Tuzak

Sunucu taraflı render veya statik oluşturma kullanan uygulamalar createRoot yerine hydrateRoot çağırmalıdır. React daha sonra DOM düğümlerini HTML’nizden yok etmek ve yeniden oluşturmak yerine hydrate edecektir (yeniden kullanacaktır).

Kısmen React ile oluşturulan bir sayfa render etmek

Sayfanız tamamen React ile oluşturulmamışsa, React tarafından yönetilen her bir üst düzey kullanıcı arayüzü parçası için bir kök oluşturmak üzere createRoot öğesini birden çok kez çağırabilirsiniz. Her kökte root.render çağrısı yaparak her kökte farklı içerikler görüntüleyebilirsiniz.

Burada, index.html dosyasında tanımlanan iki farklı DOM düğümüne iki farklı React bileşeni render edilmiştir:

import './styles.css';
import { createRoot } from 'react-dom/client';
import { Comments, Navigation } from './Components.js';

const navDomNode = document.getElementById('navigation');
const navRoot = createRoot(navDomNode); 
navRoot.render(<Navigation />);

const commentDomNode = document.getElementById('comments');
const commentRoot = createRoot(commentDomNode); 
commentRoot.render(<Comments />);

Ayrıca document.createElement() ile yeni bir DOM düğümü oluşturabilir ve bunu dokümana manuel olarak ekleyebilirsiniz.

const domNode = document.createElement('div');
const root = createRoot(domNode);
root.render(<Comment />);
document.body.appendChild(domNode); // Dokümanın herhangi bir yerine ekleyebilirsiniz

React ağacını DOM düğümünden kaldırmak ve onun tarafından kullanılan tüm kaynakları temizlemek için root.unmount. çağırın.

root.unmount();

Bu, çoğunlukla React bileşenleriniz farklı bir çatıda yazılmış bir uygulamanın içindeyse kullanışlıdır.

Bir kök bileşenin güncellenmesi

Aynı kök üzerinde render fonksiyonunu birden fazla kez çağırabilirsiniz. Önceki render edilen ile bileşen ağaç yapısı eşleştiği sürece, React state’i koruyacaktır.. Bu örnekte her saniyede tekrarlanan render çağrılarından kaynaklanan güncellemelerin yıkıcı olmadığına dikkat edin. Örneğin girdi kutusuna yazı yazıyorsunuz:

import { createRoot } from 'react-dom/client';
import './styles.css';
import App from './App.js';

const root = createRoot(document.getElementById('root'));

let i = 0;
setInterval(() => {
  root.render(<App counter={i} />);
  i++;
}, 1000);

Birden fazla kez render çağrısı yapmak nadirdir. Genellikle bileşenleriniz bunun yerine state güncellemesi yapacaktır.

Yakalanmamış hatalar için bir diyaloğu gösterme

Test Ortamı (Canary)

onUncaughtError sadece en son React Canary sürümünde mevcuttur.

Varsayılan olarak, React tüm yakalanmamış hataları konsola kaydeder. Kendi hata raporlamanızı uygulamak için, isteğe bağlı onUncaughtError root seçeneğini sağlayabilirsin:

import { createRoot } from 'react-dom/client';

const root = createRoot(
  document.getElementById('root'),
  {
    onUncaughtError: (error, errorInfo) => {
      console.error(
        'Yakalanmamış hata',
        error,
        errorInfo.componentStack
      );
    }
  }
);
root.render(<App />);

onUncaughtError seçeneği iki bağımsız değişkenle çağrılan bir fonksiyondur:

  1. Fırlatılan hata.

  2. Hatanın componentStack’ini içeren bir errorInfo nesnesi.

Hata diyalog pencerelerini görüntülemek için onUncaughtError kök seçeneğini kullanabilirsin:

import { createRoot } from "react-dom/client";
import App from "./App.js";
import {reportUncaughtError} from "./reportError";
import "./styles.css";

const container = document.getElementById("root");
const root = createRoot(container, {
  onUncaughtError: (error, errorInfo) => {
    if (error.message !== 'Known error') {
      reportUncaughtError({
        error,
        componentStack: errorInfo.componentStack
      });
    }
  }
});
root.render(<App />);

Hata yakalayıcı ile ilgili hataları görüntüleme

Test Ortamı (Canary)

onCaughtError sadece en son React Canary sürümünde mevcuttur.

Varsayılan olarak, React bir Hata yakalayıcı tarafından yakalanan tüm hataları console.error dosyasına kaydeder. Bu davranışı geçersiz kılmak için, bir Hata yakalayıcı tarafından yakalanan hataları işlemek üzere isteğe bağlı onCaughtError kök seçeneğini sağlayabilirsin. Hata yakalayıcı:

import { createRoot } from 'react-dom/client';

const root = createRoot(
  document.getElementById('root'),
  {
    onCaughtError: (error, errorInfo) => {
      console.error(
        'Yakalanan hata',
        error,
        errorInfo.componentStack
      );
    }
  }
);
root.render(<App />);

onCaughtError seçeneği iki bağımsız değişkenle çağrılan bir fonksiyondur:

  1. Hata yakalayıcı tarafından yakalanan hata.
  2. Hatanın componentStack’ini içeren bir errorInfo nesnesi.

Hata diyologlarını görüntülemek veya bilinen hataları günlükten filtrelemek için onCaughtError kök seçeneğini kullanabilirsin:

import { createRoot } from "react-dom/client";
import App from "./App.js";
import {reportCaughtError} from "./reportError";
import "./styles.css";

const container = document.getElementById("root");
const root = createRoot(container, {
  onCaughtError: (error, errorInfo) => {
    if (error.message !== 'Known error') {
      reportCaughtError({
        error, 
        componentStack: errorInfo.componentStack,
      });
    }
  }
});
root.render(<App />);

Kurtarılabilir hatalar için bir diyoloğu görüntüleme

React, render etme sırasında atılan bir hatadan kurtulmayı denemek için bir bileşeni otomatik olarak ikinci kez render edebilir. Başarılı olursa, React geliştiriciyi bilgilendirmek için konsola kurtarılabilir bir hata günlüğü kaydeder. Bu davranışı geçersiz kılmak için, isteğe bağlı onRecoverableError kök seçeneğini sağlayabilirsin:

import { createRoot } from 'react-dom/client';

const root = createRoot(
  document.getElementById('root'),
  {
    onRecoverableError: (error, errorInfo) => {
      console.error(
        'Kurtarılabilir hata',
        error,
        error.cause,
        errorInfo.componentStack,
      );
    }
  }
);
root.render(<App />);

onRecoverableError seçeneği iki bağımsız değişkenle çağrılan bir fonksiyondur:

  1. React’in fırlattığı hata. Bazı hatalar, error.cause olarak orijinal nedeni içerebilir.

  2. Hatanın componentStack’ini içeren bir errorInfo nesnesi.

Hata diyaloglarını görüntülemek için onRecoverableError kök seçeneğini kullanabilirsin:

import { createRoot } from "react-dom/client";
import App from "./App.js";
import {reportRecoverableError} from "./reportError";
import "./styles.css";

const container = document.getElementById("root");
const root = createRoot(container, {
  onRecoverableError: (error, errorInfo) => {
    reportRecoverableError({
      error,
      cause: error.cause,
      componentStack: errorInfo.componentStack,
    });
  }
});
root.render(<App />);

Sorun Giderme

Bir kök oluşturdum, fakat hiçbir şey görüntülenmiyor.

Uygulamanızı kök içine gerçekten render etmeyi unutmadığınızdan emin olun:

import { createRoot } from 'react-dom/client';
import App from './App.js';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

Bunu yapana kadar hiçbir şey görüntülenmez.

Bir hata alıyorum: “root.render’a ikinci bir argüman geçtiniz”

Sık yapılan bir hata, createRoot seçeneklerini root.render(...) öğesine aktarmaktır:

Console
Uyarı: root.render(…) öğesine ikinci bir bağımsız değişken ilettiniz, ancak bu öğe yalnızca bir bağımsız değişken kabul eder.

Düzeltmek için, kök seçeneklerini root.render(...) yerine createRoot(...) öğesine aktarın:

// 🚩 Wrong: root.render only takes one argument.
root.render(App, {onUncaughtError});

// ✅ Correct: pass options to createRoot.
const root = createRoot(container, {onUncaughtError}); 
root.render(<App />);

Bir hata alıyorum: “Hedef kapsayıcı bir DOM öğesi değil”

Bu hata, createRoot öğesine aktardığınız şeyin bir DOM düğümü olmadığı anlamına gelir.

Ne olduğundan emin değilseniz, yazdırmayı(log) deneyin:

const domNode = document.getElementById('root');
console.log(domNode); // ???
const root = createRoot(domNode);
root.render(<App />);

Örneğin, domNode null ise, getElementById null döndürmüş demektir. Bu, çağrınız sırasında dokümanda verilen kimliğe sahip bir düğüm yoksa gerçekleşir. Bunun birkaç nedeni olabilir:

  1. Aradığınız ID, HTML dosyasında kullandığınız ID’den farklı olabilir. Yazım hatalarını kontrol edin!
  2. Paketinizin <script> etiketi, HTML’de kendisinden sonra görünen herhangi bir DOM düğümünü “göremez”.

Bu hatayı almanın bir başka yaygın yolu da createRoot(domNode) yerine createRoot(<App />) yazmaktır.

Bir hata alıyorum: “Fonksiyonlar bir React alt elemanı olarak geçerli değildir.”

Bu hata, root.rendera aktardığınız şeyin bir React bileşeni olmadığı anlamına gelir.

Bu, root.render öğesini <Component /> yerine Component ile çağırırsanız meydana gelebilir:

// 🚩 Yanlış: App bir fonksiyondur, Bileşen değildir.
root.render(App);

// ✅ Doğru: <App /> bir bileşendir.
root.render(<App />);

Veya root.render’a fonksiyonu çağırmanın sonucu yerine fonksiyonun kendisini iletirseniz:

// 🚩 Yanlış: createApp bir fonksiyondur, bileşen değildir.
root.render(createApp);

// ✅ Doğru: Bir bileşen döndürmek için createApp'i çağırın.
root.render(createApp());

Sunucu tarafından render edilen HTML’im sıfırdan yeniden oluşturuluyor

Uygulamanız sunucu tarafından render ediliyorsa ve React tarafından oluşturulan ilk HTML’yi içeriyorsa, bir kök oluşturmanın ve root.render çağrısının tüm bu HTML’yi sildiğini ve ardından tüm DOM düğümlerini sıfırdan yeniden oluşturduğunu fark edebilirsiniz. Bu daha yavaş olabilir, odak ve kaydırma konumlarını sıfırlayabilir ve diğer kullanıcı girdilerini kaybedebilir.

Sunucu tarafından render edilen uygulamalar createRoot yerine hydrateRoot kullanmalıdır:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(
  document.getElementById('root'),
  <App />
);

API’sinin farklı olduğunu unutmayın. Özellikle, başka bir root.render çağrısı genellikle gerçekleşmeyecektir.

PreviousClient APIs
NexthydrateRoot