Kurs JavaScript i React · Moduł 10: Ekosystem i przyszłość React
React 19 - Nowy sposób przekazywania ref (bez forwardRef)
W tej lekcji6
Panel nawigacyjny chce ustawić fokus na polu współrzędnych ukrytym w komponencie potomnym. ref daje właśnie taki bezpośredni dostęp do elementu DOM, ale przypięty do własnego komponentu przez lata nie docierał do środka: React traktował go specjalnie i nie przekazywał w propsach. Trzeba było owijać komponent w forwardRef, jak w dodatkowy przekaźnik sygnału. W React 19 ta długo oczekiwana zmiana wreszcie nadeszła, podobnie jak nowe systemy komunikacji na statkach eliminują skomplikowane przekaźniki.
Stary sposób z forwardRef (React 18 i wcześniej)
W poprzednich wersjach Reacta, żeby przekazać ref do komponentu potomnego, trzeba było użyć forwardRef. Funkcja komponentu dostawała ref jako drugi argument, obok propsów:
import { forwardRef, useRef } from 'react';
// Stary sposób - wymaga forwardRef
const SpaceshipButton = forwardRef((props, ref) => {
return (
<button ref={ref} className="spaceship-btn" {...props}>
{props.children}
</button>
);
});
// Użycie
function MissionControl() {
const buttonRef = useRef(null);
const focusButton = () => {
buttonRef.current?.focus();
};
return (
<div>
<SpaceshipButton ref={buttonRef}>
Uruchom silniki
</SpaceshipButton>
<button onClick={focusButton}>Fokus na przycisk</button>
</div>
);
}MissionControl tworzy buttonRef przez useRef i po kliknięciu wywołuje focus() na prawdziwym przycisku. Działa, ale komponent ma nietypową sygnaturę (props, ref) i dodatkowe opakowanie, o którym trzeba pamiętać przy każdym takim komponencie.
Nowy sposób w React 19 - ref jako prop
W React 19 ref jest zwykłym propem komponentu funkcyjnego. Wyciągasz go z propsów jak każdą inną wartość:
import { useRef } from 'react';
// Nowy sposób w React 19 - ref to po prostu prop!
function SpaceshipButton({ ref, children, ...props }) {
return (
<button ref={ref} className="spaceship-btn" {...props}>
{children}
</button>
);
}
// Użycie - dokładnie tak samo!
function MissionControl() {
const buttonRef = useRef(null);
const focusButton = () => {
buttonRef.current?.focus();
};
return (
<div>
<SpaceshipButton ref={buttonRef}>
Uruchom silniki
</SpaceshipButton>
<button onClick={focusButton}>Fokus na przycisk</button>
</div>
);
}Zmieniła się tylko definicja: znika forwardRef, a ref trafia do destrukturyzacji obok children. Użycie w MissionControl jest dokładnie takie samo. Zasada dotyczy komponentów funkcyjnych, bo w klasowych ref nadal wskazuje instancję i nie trafia do propsów.
Praktyczne przykłady
1. Input z auto-focus
Formularz współrzędnych pokazuje, jak ref ułatwia nawigację klawiaturą. Każdy CoordinateInput przekazuje ref prosto do elementu input:
// React 19 - prosty komponent inputa
function CoordinateInput({ ref, label, ...props }) {
return (
<div className="coordinate-field">
<label>{label}</label>
<input ref={ref} {...props} />
</div>
);
}
function NavigationPanel() {
const latitudeRef = useRef(null);
const longitudeRef = useRef(null);
useEffect(() => {
// Auto-focus na pierwszy input
latitudeRef.current?.focus();
}, []);
const handleLatitudeEnter = (e) => {
if (e.key === 'Enter') {
longitudeRef.current?.focus();
}
};
return (
<form className="nav-panel">
<h2>Wprowadź współrzędne docelowe</h2>
<CoordinateInput
ref={latitudeRef}
label="Szerokość galaktyczna"
onKeyDown={handleLatitudeEnter}
/>
<CoordinateInput
ref={longitudeRef}
label="Długość galaktyczna"
/>
<button type="submit">Ustaw kurs</button>
</form>
);
}Po zamontowaniu efekt ustawia fokus na polu szerokości, a Enter przenosi go do długości. CoordinateInput pozostaje zwykłą funkcją bez opakowania, a pozostałe propsy, jak onKeyDown, trafiają do inputa przez ...props.
useImperativeHandle - nadal użyteczny
Czasem nie chcesz oddawać rodzicowi całego elementu DOM, tylko wybrane polecenia. useImperativeHandle nadal działa, ale teraz bez forwardRef: podajesz mu ref odebrany z propsów:
import { useImperativeHandle, useRef } from 'react';
function VideoPlayer({ ref, src }) {
const videoRef = useRef(null);
// Eksponuj tylko wybrane metody
useImperativeHandle(ref, () => ({
play: () => videoRef.current?.play(),
pause: () => videoRef.current?.pause(),
seek: (time) => {
if (videoRef.current) {
videoRef.current.currentTime = time;
}
},
getCurrentTime: () => videoRef.current?.currentTime || 0,
}), []);
return (
<video ref={videoRef} src={src} className="space-video">
Twoja przeglądarka nie obsługuje wideo.
</video>
);
}
function MediaController() {
const playerRef = useRef(null);
return (
<div>
<VideoPlayer ref={playerRef} src="/space-documentary.mp4" />
<div className="controls">
<button onClick={() => playerRef.current?.play()}>
Odtwórz
</button>
<button onClick={() => playerRef.current?.pause()}>
Pauza
</button>
<button onClick={() => playerRef.current?.seek(0)}>
Od początku
</button>
</div>
</div>
);
}Rodzic widzi tylko play, pause, seek i getCurrentTime, a nie cały element video. To bezpieczniejsze API, bo nikt z zewnątrz nie zmieni przypadkiem atrybutów odtwarzacza.
Migracja z forwardRef
Jeśli masz kod z forwardRef, migracja jest prosta: przenosisz ref z drugiego argumentu do propsów:
// Przed (React 18)
const OldComponent = forwardRef(function OldComponent(props, ref) {
return <div ref={ref}>{props.children}</div>;
});
// Po (React 19)
function NewComponent({ ref, children }) {
return <div ref={ref}>{children}</div>;
}
// Użycie pozostaje identyczne!
function Panel() {
const oldRef = useRef(null);
const newRef = useRef(null);
return (
<>
<OldComponent ref={oldRef}>Stary</OldComponent>
<NewComponent ref={newRef}>Nowy</NewComponent>
</>
);
}Miejsca użycia się nie zmieniają, więc możesz migrować komponent po komponencie. Nie musisz się też spieszyć: forwardRef w React 19 nadal działa i nie jest jeszcze oznaczony jako przestarzały (deprecated), dokumentacja zapowiada to dopiero w przyszłej wersji.
Podsumowanie
React 19 wprowadza znaczące uproszczenie w przekazywaniu referencji:
- ref jest zwykłym propem - w komponentach funkcyjnych nie wymaga specjalnego traktowania
- forwardRef nie jest już potrzebny - nadal działa, a dokumentacja zapowiada, że w przyszłej wersji zostanie oznaczony jako przestarzały (deprecated)
- useImperativeHandle działa bez forwardRef - przekaż ref jako prop
- Callback refs działają jak dawniej - a od React 19 mogą też zwrócić funkcję sprzątającą, którą React wywoła przy odłączeniu elementu
- TypeScript - ref opisujesz w typie propsów jak każdy inny prop, np.
React.Ref<HTMLInputElement>
W nowym kodzie polecam Ci od razu pisać komponenty z ref w propsach, a stary kod migrować przy okazji innych zmian. Przyda się to w każdej bibliotece komponentów, bo przyciski i pola muszą udostępniać ref do fokusu i pomiarów. To uproszczenie sprawia, że komponenty są bardziej przewidywalne i łatwiejsze do zrozumienia.
Pamiętaj: w React 19 ref to zwykły kanał łączności między modułami - podłączasz go jak każdy inny prop, bez dodatkowego przekaźnika. W przykładzie poniżej stary przycisk z forwardRef i nowe komponenty z ref w propsach działają obok siebie, a okno dialogowe udostępnia rodzicowi metody przez useImperativeHandle.
Kod do tej lekcji: App.jsx
import { forwardRef, useImperativeHandle, useRef, useState } from 'react';
// React 19: ref jest zwykłym propem komponentu funkcyjnego.
// forwardRef nadal działa, ale nie jest już potrzebny.
// Stary sposób (React 18) - wciąż działa w React 19
const OldSpaceButton = forwardRef(function OldSpaceButton(props, ref) {
return <button ref={ref} style={{ ...styles.button, background: '#778da9' }} {...props} />;
});
// Nowy sposób w React 19 - ref wyciągasz z propsów jak każdą inną wartość
function SpaceButton({ ref, children, variant = 'primary', ...props }) {
const colors = {
primary: { background: '#00d4ff', color: '#0a0e27' },
danger: { background: '#ff6b6b', color: '#fff' },
success: { background: '#00ff88', color: '#0a0e27' },
};
return (
<button ref={ref} style={{ ...styles.button, ...(colors[variant] || colors.primary) }} {...props}>
{children}
</button>
);
}
function SpaceInput({ ref, label, ...props }) {
return (
<label style={styles.field}>
<span style={styles.label}>{label}</span>
<input ref={ref} style={styles.input} {...props} />
</label>
);
}
// useImperativeHandle z ref z propsów: rodzic dostaje tylko open, close i toggle
function SpaceDialog({ ref, title, children }) {
const [isOpen, setIsOpen] = useState(false);
useImperativeHandle(ref, () => ({
open: () => setIsOpen(true),
close: () => setIsOpen(false),
toggle: () => setIsOpen(prev => !prev),
}), []);
if (!isOpen) return null;
return (
<div style={styles.overlay}>
<div style={styles.dialog}>
<h3 style={{ color: '#00d4ff', margin: '0 0 12px' }}>{title}</h3>
{children}
<button onClick={() => setIsOpen(false)} style={styles.closeButton}>Zamknij</button>
</div>
</div>
);
}
export default function App() {
const buttonRef = useRef(null);
const oldButtonRef = useRef(null);
const inputRef = useRef(null);
const dialogRef = useRef(null);
const [log, setLog] = useState([]);
const addLog = message => setLog(prev => [message, ...prev].slice(0, 6));
return (
<div style={styles.page}>
<div style={{ maxWidth: '600px', margin: '0 auto' }}>
<h1 style={styles.title}>React 19: ref jako prop</h1>
<p style={styles.subtitle}>forwardRef nie jest już potrzebny, choć nadal działa</p>
<section style={styles.card}>
<h3 style={styles.cardTitle}>Przycisk z ref w propsach</h3>
<div style={styles.row}>
<SpaceButton ref={buttonRef} onClick={() => addLog('Kliknięto przycisk z ref')}>
Uruchom silniki
</SpaceButton>
<SpaceButton variant="success" onClick={() => { buttonRef.current?.focus(); addLog('Fokus na przycisku (nowy sposób)'); }}>
Ustaw fokus
</SpaceButton>
</div>
</section>
<section style={styles.card}>
<h3 style={styles.cardTitle}>Stary przycisk z forwardRef</h3>
<div style={styles.row}>
<OldSpaceButton ref={oldButtonRef} onClick={() => addLog('Kliknięto stary przycisk')}>
Stary przekaźnik
</OldSpaceButton>
<SpaceButton variant="success" onClick={() => { oldButtonRef.current?.focus(); addLog('Fokus na przycisku (forwardRef)'); }}>
Ustaw fokus
</SpaceButton>
</div>
</section>
<section style={styles.card}>
<h3 style={styles.cardTitle}>Pole tekstowe z ref w propsach</h3>
<SpaceInput ref={inputRef} label="Nazwa misji" placeholder="Wpisz nazwę..." />
<SpaceButton onClick={() => { inputRef.current?.focus(); addLog('Fokus na polu tekstowym'); }}>
Ustaw fokus na polu
</SpaceButton>
</section>
<section style={styles.card}>
<h3 style={styles.cardTitle}>Okno dialogowe z useImperativeHandle</h3>
<div style={styles.row}>
<SpaceButton onClick={() => { dialogRef.current?.open(); addLog('Otwarto okno'); }}>Otwórz okno</SpaceButton>
<SpaceButton variant="danger" onClick={() => { dialogRef.current?.close(); addLog('Zamknięto okno'); }}>Zamknij okno</SpaceButton>
</div>
</section>
<SpaceDialog ref={dialogRef} title="Komunikat z mostka">
<p style={{ margin: 0 }}>To okno udostępnia rodzicowi tylko metody open, close i toggle przez useImperativeHandle.</p>
</SpaceDialog>
<section style={styles.card}>
<h3 style={styles.cardTitle}>Dziennik zdarzeń</h3>
{log.length === 0 ? (
<p style={styles.muted}>Kliknij przyciski powyżej...</p>
) : (
log.map((entry, i) => <div key={i} style={styles.logRow}>{entry}</div>)
)}
</section>
</div>
</div>
);
}
const styles = {
page: { minHeight: '100vh', background: 'linear-gradient(135deg, #0a0e27 0%, #1a1a3e 100%)', padding: '24px', color: '#e0e1dd', fontFamily: 'system-ui, sans-serif' },
title: { textAlign: 'center', color: '#00d4ff', margin: '0 0 6px' },
subtitle: { textAlign: 'center', color: '#8892b0', margin: '0 0 18px', fontSize: '14px' },
card: { background: 'rgba(0,0,0,0.3)', padding: '16px', borderRadius: '12px', marginBottom: '12px' },
cardTitle: { color: '#64ffda', margin: '0 0 10px', fontSize: '15px' },
row: { display: 'flex', gap: '8px', flexWrap: 'wrap' },
button: { padding: '9px 16px', border: 'none', borderRadius: '8px', cursor: 'pointer', fontWeight: 'bold', fontSize: '14px', color: '#0a0e27' },
field: { display: 'block', marginBottom: '10px' },
label: { display: 'block', color: '#8892b0', fontSize: '13px', marginBottom: '4px' },
input: { width: '100%', boxSizing: 'border-box', padding: '9px 12px', background: 'rgba(255,255,255,0.08)', border: '1px solid rgba(0,212,255,0.3)', borderRadius: '8px', color: '#e0e1dd', fontSize: '14px' },
overlay: { position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.7)', display: 'flex', alignItems: 'center', justifyContent: 'center', zIndex: 1000 },
dialog: { background: '#1a1a3e', padding: '24px', borderRadius: '12px', border: '1px solid rgba(0,212,255,0.3)', maxWidth: '400px', width: '90%' },
closeButton: { marginTop: '16px', padding: '8px 16px', background: 'rgba(255,255,255,0.1)', color: '#e0e1dd', border: '1px solid rgba(255,255,255,0.2)', borderRadius: '6px', cursor: 'pointer' },
muted: { color: '#8892b0', fontSize: '13px', margin: 0 },
logRow: { fontSize: '12px', color: '#8892b0', padding: '2px 0', fontFamily: 'monospace' },
};Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jak przekazać ref do komponentu funkcyjnego w React 19?
2. Jaki jest status forwardRef w React 19?
Zadania praktyczne w grze
- Klikanie w kolejności
Ułóż nowy sposób definiowania komponentu z ref w React 19: