React Suspense w praktyce - kiedy działa fallback, a kiedy nie?

17 października 2026

Programista siedzi przy biurku z dwoma monitorami, otoczony roślinami. Napięcie rośnie, gdy kod na ekranach zaczyna się zmieniać.

Otwierasz widok produktu, a obok ceny wciąż kręci się spinner, choć reszta strony mogłaby już działać. React Suspense pozwala pokazać w takim miejscu zastępczy interfejs, gdy część komponentu czeka na obsługiwane przez React ładowanie, ale samo opakowanie komponentu w granicę Suspense nie sprawi, że dowolne żądanie `fetch` zacznie ją uruchamiać.

Kod React z importem Suspense, budzący react suspense.

Suspense porządkuje oczekiwanie, jeśli źródło danych go obsługuje

  • Granica Suspense wyświetla `fallback` zamiast zawartości potomnej, która zawiesiła renderowanie.
  • Efekt `useEffect` i zwykły handler `fetch` nie uruchamiają Suspense.
  • Promise przekazany do `use` musi być współdzielony między renderami, a nie tworzony od nowa w komponencie.
  • Error Boundary obsługuje błąd odrzuconego Promise; sam `fallback` Suspense służy do oczekiwania.
  • Granice lokalne pozwalają zachować widoczną część strony, gdy ładuje się tylko panel lub lista.

Fallback pojawia się tylko wtedy, gdy komponent naprawdę zawiesi renderowanie

Wyobraź sobie kartę produktu: nazwa i cena są gotowe, ale galeria czeka na kod pobierany przez `lazy`. Owijasz galerię w `}>`, więc użytkownik widzi szkielet w miejscu zdjęć, a reszta karty pozostaje na ekranie. Granica obejmuje tylko swoje dzieci, dlatego położenie jej w drzewie komponentów określa, jak duży fragment interfejsu zostanie zastąpiony.

Gdy React wykryje zawieszenie w poddrzewie, pokaże `fallback` najbliższej granicy Suspense. W aplikacji z renderowaniem po stronie serwera granice mogą też pozwolić przesyłać HTML etapami, zamiast czekać z całą stroną na najwolniejszą sekcję. Nie każda asynchroniczność jest jednak widoczna dla Suspense: żądanie uruchomione w efekcie lub obsłudze kliknięcia samo z siebie nie wstrzymuje renderowania. Dokumentacja React dotycząca strumieniowania HTML opisuje ten podział.

Sam `fetch` w `useEffect` nie uruchomi granicy Suspense

Jeśli komponent pobiera dane w `useEffect`, zwykle sam przechowuje stan typu `loading`, `error` i `data`. W takim układzie renderuje się od razu, a efekt wykonuje się po renderze, więc Suspense nie ma sygnału, że powinien zastąpić zawartość swoim fallbackiem. Prawdę mówiąc, mieszanie tych dwóch modeli bez jasnego podziału często kończy się podwójną obsługą stanu ładowania.

W React 19 możesz odczytać Promise przez `use(promise)`, a komponent zawiesi renderowanie do czasu rozstrzygnięcia Promise. To jednak nie oznacza, że każde `fetch` można bezpiecznie wpisać do renderu. Oficjalne wskazówki React rekomendują mechanizm wbudowany w używany framework albo bibliotekę i cache obsługujący Suspense, zamiast samodzielnego, przypadkowego pobierania danych w komponencie. Dokumentacja React o synchronizacji z efektami omawia ograniczenia pobierania danych w efektach.

Nowy Promise w każdym renderze może zatrzymać widok w stanie ładowania

Jest tu pułapka, która potrafi wyglądać jak zawieszony spinner bez końca. Jeśli podczas każdego renderu tworzysz nowy Promise, React może ponowić render po zawieszeniu, dostać kolejną instancję Promise i ponownie pokazać fallback, zanim poprzednia zdąży zostać wykorzystana.

function Albums({ url }) {
  const albums = use(fetch(url)); // nowy Promise przy każdym renderze
  return ;
}

Rozwiązaniem nie jest samo przeniesienie wywołania do `useMemo` bez sprawdzenia całego przepływu. Komponent powinien otrzymać stabilny Promise z cache, frameworka albo komponentu serwerowego; React podkreśla też, że wywołanie `.then()` w renderze może utworzyć nowy Promise, nawet gdy wyjściowe żądanie pochodzi z cache. Dokumentacja `use` w React opisuje ten przypadek oraz przekazywanie Promise między komponentami.

React 19 pokazuje fallback wcześniej, ale nie rozwiązuje problemu złej granicy

W React 19 zachowanie przy zawieszeniu zmieniło się w sposób zauważalny dla interfejsu: React może zatwierdzić fallback najbliższej granicy, zanim zakończy renderowanie całego drzewa rodzeństwa, a potem przygotować kolejne żądania lazy w zawieszonym poddrzewie. Efekt jest praktyczny: stan ładowania może pojawić się szybciej, ale nadal trzeba rozsądnie wybrać rozmiar i położenie granicy. Informację o tej zmianie zawiera przewodnik aktualizacji do React 19.

Przy redagowaniu interfejsu wybór granicy traktuję jako decyzję o tym, co użytkownik ma móc robić podczas oczekiwania. Uważam, że zwykle lepiej zacząć od osobnego fallbacku dla wolnego panelu niż zasłaniać nim cały ekran, chyba że bez brakujących danych nie da się sensownie pokazać pozostałej treści.

Sytuacja Prawdopodobna przyczyna Co zrobić
Spinner z `useEffect` nie pojawia się przez Suspense Efekt nie wstrzymuje renderowania Pozostaw osobny stan ładowania albo użyj źródła danych z obsługą Suspense
Fallback wraca przy kolejnych renderach Promise jest tworzony ponownie w komponencie Przekaż stabilny Promise z cache lub frameworka
Cała strona znika, choć ładuje się tylko lista Granica obejmuje zbyt duży fragment drzewa Przenieś ją bliżej listy i przygotuj dla niej lokalny szkielet
Po odrzuceniu Promise użytkownik widzi błąd zamiast ładowania Oczekiwanie zakończyło się błędem, który obsługuje Error Boundary Dodaj Error Boundary z komunikatem i, jeśli pasuje do przepływu, opcją ponowienia

Osobny fallback i obsługa błędu tworzą czytelniejszy przepływ

Granica Suspense odpowiada na pytanie „co pokazać, gdy dane jeszcze się ładują?”, a Error Boundary na inne: „co zrobić, gdy Promise zakończył się błędem?”. W projekcie warto więc rozdzielić te odpowiedzialności. Fallback powinien przypominać kształt treści, która zaraz się pojawi: szare bloki dla listy produktów zwykle informują lepiej niż spinner na środku całego ekranu.

Przy błędzie zaprojektuj osobny komunikat, który nie udaje stanu ładowania. Może zawierać krótki opis problemu i przycisk ponowienia, o ile aplikacja potrafi rzeczywiście ponowić żądanie i odświeżyć Promise. Granicę błędu umieść tak, by awaria jednego panelu nie wyłączała niezależnych części widoku.

Dobierz Suspense do zakresu treści, która może poczekać

Jeśli treść wymaga frameworka albo biblioteki obsługującej Suspense, granica daje wygodny sposób na kontrolowanie lokalnego stanu ładowania. Jeśli korzystasz z prostego `fetch` w efekcie, dodanie `` nie zmieni jego działania; bardziej uczciwy wobec interfejsu będzie wtedy jawny stan ładowania obsłużony w komponencie. Najpierw ustal, co faktycznie zawiesza renderowanie, a dopiero potem dobieraj wygląd fallbacku.

W React 19 oficjalna dokumentacja wskazuje wersję 19.3 jako najnowszą. Dla decyzji projektowej ważniejsza od numeru wersji pozostaje jednak prosta zasada: karta produktu może być gotowa, gdy ładuje się galeria, a cały ekran nie musi czekać na jeden wolny panel. Strona wersji React pozwala zweryfikować bieżący numer wydania.

FAQ - Najczęstsze pytania

useEffect uruchamia się po renderze, więc nie wstrzymuje go i React nie dostaje sygnału do pokazania fallbacku. W tym modelu komponent powinien jawnie obsługiwać stan loading, error i data albo korzystać ze źródła danych, frameworka lub biblioteki z obsługą Suspense.

Promise powinien być stabilny i współdzielony, na przykład dostarczony przez cache, framework lub komponent serwerowy. Tworzenie fetch(...) podczas każdego renderu daje nową instancję Promise, przez co React może ponownie zawieszać widok. Samo przeniesienie wywołania do useMemo nie jest automatycznie rozwiązaniem.

Umieść ją blisko wolnego poddrzewa, na przykład wokół galerii lub listy, aby fallback zastąpił tylko jego zawartość, a nazwa, cena i inne niezależne elementy pozostały widoczne. Granica obejmuje swoje dzieci, więc objęcie nią całej strony może niepotrzebnie ukryć gotową treść.

Suspense pokazuje fallback podczas oczekiwania, natomiast Error Boundary obsługuje błąd odrzuconego Promise. Komunikat błędu może zawierać opcję ponowienia, jeśli aplikacja potrafi odświeżyć Promise, a granicę błędu warto umieścić tak, by awaria jednego panelu nie wyłączała reszty widoku.
Oceń artykuł

Średnia: 4.3 / 5 · 6 ocen

Tagi

react promise fallback suspense error boundary

Udostępnij artykuł

Komentarze (0)
Dodaj komentarz