React 19: novidades, APIs removidas e como atualizar

O React 19 é a versão principal do React lançada em dezembro de 2024. Ele adiciona Actions (funções assíncronas que gerenciam estado pendente, erros e formulários), os hooks useActionState, useOptimistic e use, ref como prop comum e tags <title> e <meta> que o React move para o head do documento. O React 19.2 (outubro de 2025) adicionou <Activity> e useEffectEvent.

Todos os exemplos abaixo rodam no React 19.2. Aqui está uma Action: uma função assíncrona passada para um formulário, com o estado pendente e o erro retornado tratados pelo useActionState.

import { useActionState } from 'react';

function saveName(name) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(resolve, 800));
}

async function updateName(previousState, formData) {
    const name = formData.get('name').trim();
    if (!name) {
        return { error: 'Please type a name.', saved: previousState.saved };
    }
    await saveName(name);
    return { error: null, saved: name };
}

export default function App() {
    const [state, formAction, isPending] = useActionState(updateName, {
        error: null,
        saved: null,
    });

    return (
        <form action={formAction}>
            <input name="name" placeholder="Your name" />
            <button type="submit" disabled={isPending}>
                {isPending ? 'Saving...' : 'Save'}
            </button>
            {state.error && <p style={{ color: 'crimson' }}>{state.error}</p>}
            {state.saved && <p>Saved as {state.saved}.</p>}
        </form>
    );
}

Aperte Save com o campo vazio para ver o erro, depois digite um nome e salve: o botão mostra "Saving..." por 800 ms. Não há useState para o erro, nem indicador isLoading, nem e.preventDefault().

Actions e form actions

No React 18 você escrevia os mesmos passos para todo formulário: impedir o envio padrão, ligar um indicador de carregamento, aguardar a requisição, guardar um erro, desligar o indicador. O React 19 chama de Action uma função que faz trabalho assíncrono dentro de uma transição, e cuida dessa burocracia por você.

• startTransition (e useTransition) agora aceitam uma função assíncrona. isPending continua true até a função inteira terminar.
• <form action={fn}> chama fn com o FormData do formulário quando ele é enviado. Ela executa como uma Action e, quando termina, o React reinicia os campos não controlados do formulário.
• <button formAction={fn}> dá a um botão de envio a própria action.
• O useActionState guarda o último valor que a action retornou, então uma action pode retornar uma mensagem de erro ou o registro salvo.
• O useFormStatus de react-dom permite que um componente dentro de um formulário leia se esse formulário está sendo enviado, sem passar props para baixo. Ele precisa de um <form> pai, então aparece aqui em um bloco estático:

import { useFormStatus } from 'react-dom';

function SubmitButton() {
    const { pending } = useFormStatus();
    return <button disabled={pending}>{pending ? 'Sending...' : 'Send'}</button>;
}

useOptimistic

O useOptimistic mostra o resultado que você espera enquanto uma Action ainda está executando e volta ao estado real quando a Action termina. Um contador de curtidas pode subir no momento do clique e voltar se a requisição falhar.

const [optimisticLikes, addOptimisticLike] = useOptimistic(likes, (current, delta) => current + delta);

A página do useOptimistic tem um exemplo executável com uma API falsa que falha de propósito, para você ver a reversão.

A API use

O use lê um valor de uma promise ou de um context. Com uma promise, ele suspende o componente até a promise resolver, e o <Suspense> mais próximo mostra o fallback enquanto isso. Ao contrário de todos os outros hooks, o use pode ser chamado dentro de um if ou de um loop, e depois de um return antecipado.

O React 19 também permite renderizar <ThemeContext value="dark"> diretamente em vez de <ThemeContext.Provider>. Os dois aparecem neste exemplo:

import { createContext, use, useState } from 'react';

const ThemeContext = createContext('light');

function Badge({ show }) {
    if (!show) return null;
    // A normal hook could not be called after an early return. use can.
    const theme = use(ThemeContext);
    const dark = theme === 'dark';
    return (
        <span style={{ padding: '2px 8px', background: dark ? '#222' : '#eee', color: dark ? '#fff' : '#222' }}>
            Theme: {theme}
        </span>
    );
}

export default function App() {
    const [theme, setTheme] = useState('light');
    const [show, setShow] = useState(true);

    return (
        <ThemeContext value={theme}>
            <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>Switch theme</button>
            <button onClick={() => setShow(!show)}>{show ? 'Hide' : 'Show'} badge</button>
            <p>
                <Badge show={show} />
            </p>
        </ThemeContext>
    );
}

ref como prop e limpeza de ref

Um componente de função agora recebe ref como qualquer outra prop. Você não precisa mais envolvê-lo em forwardRef para passar uma ref até um elemento do DOM.

import { useRef } from 'react';

function TextField({ label, ref }) {
    return (
        <label>
            {label} <input ref={ref} />
        </label>
    );
}

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

    return (
        <div>
            <TextField label="Email" ref={inputRef} />
            <button onClick={() => inputRef.current.focus()}>Focus the field</button>
        </div>
    );
}

Uma ref callback também pode retornar uma função de limpeza. O React a chama quando o elemento sai da tela, do mesmo jeito que funciona a limpeza de um efeito. Uma callback que não retorna nada continua sendo chamada com null na remoção, como no React 18.

import { useState } from 'react';

export default function App() {
    const [visible, setVisible] = useState(true);

    return (
        <div>
            <button onClick={() => setVisible(!visible)}>{visible ? 'Remove' : 'Add'} the box</button>
            {visible && (
                <div
                    ref={(node) => {
                        console.log('attached to', node.tagName);
                        return () => console.log('cleanup: detached');
                    }}
                    style={{ marginTop: 8, padding: 12, background: '#e8f0fe' }}
                >
                    A box with a ref
                </div>
            )}
        </div>
    );
}

Clique no botão algumas vezes e leia o console: cada remoção registra a linha de limpeza, cada retorno registra attached to DIV.

Metadados do documento

Você pode renderizar <title>, <meta> e <link> em qualquer lugar de um componente, e o React os move para o <head>. Um componente de página pode definir o próprio título sem uma biblioteca como o react-helmet.

import { useEffect, useState } from 'react';

function Article({ title }) {
    return (
        <article>
            <title>{title}</title>
            <meta name="description" content={`An article about ${title}`} />
            <h3>{title}</h3>
        </article>
    );
}

export default function App() {
    const [title, setTitle] = useState('Hooks');

    useEffect(() => {
        console.log('document.title is now:', document.title);
    }, [title]);

    return (
        <div>
            <button onClick={() => setTitle(title === 'Hooks' ? 'Actions' : 'Hooks')}>Open the other article</button>
            <Article title={title} />
        </div>
    );
}

A prévia não tem uma aba de navegador para mostrar, então o efeito registra document.title no lugar. Troque de artigo e o título registrado acompanha.

As folhas de estilo receberam o mesmo tratamento: <link rel="stylesheet" href="..." precedence="default" /> dentro de um componente é inserido no head uma vez, na ordem de precedência, e o React espera por ele antes de mostrar o conteúdo que precisa dele. Um <script async src="..."> renderizado por vários componentes carrega só uma vez. O react-dom também exporta preload, preinit, preconnect e prefetchDNS para dicas de recursos.

Activity e useEffectEvent (React 19.2)

<Activity mode="hidden"> esconde os filhos sem descartar o estado deles. O React esconde o DOM, executa as limpezas dos efeitos e restaura tudo quando o modo volta a ser "visible". Combina com abas e painéis para os quais você espera que o usuário volte.

import { Activity, useEffect, useState } from 'react';

function Notes() {
    const [text, setText] = useState('');
    useEffect(() => {
        console.log('Notes effect: setup');
        return () => console.log('Notes effect: cleanup');
    }, []);
    return <textarea value={text} onChange={(e) => setText(e.target.value)} rows={3} placeholder="Type a note" />;
}

export default function App() {
    const [tab, setTab] = useState('notes');

    return (
        <div>
            <button onClick={() => setTab('notes')}>Notes</button>
            <button onClick={() => setTab('about')}>About</button>
            <div style={{ marginTop: 8 }}>
                <Activity mode={tab === 'notes' ? 'visible' : 'hidden'}>
                    <Notes />
                </Activity>
                {tab === 'about' && <p>Your note is kept while this tab is open.</p>}
            </div>
        </div>
    );
}

Digite uma anotação, vá para About e volte. O texto continua lá, e o console mostra que o efeito fez a limpeza enquanto estava escondido. Substitua o wrapper <Activity> por {tab === 'notes' && <Notes />} e a anotação se perde a cada troca.

O useEffectEvent tira uma função das dependências de um efeito. A função sempre vê as props e o estado mais recentes, mas mudá-los não reinicia o efeito:

function ChatRoom({ roomId, theme }) {
    const onConnected = useEffectEvent(() => {
        showNotification('Connected!', theme);
    });

    useEffect(() => {
        const connection = createConnection(roomId);
        connection.on('connected', () => onConnected());
        connection.connect();
        return () => connection.disconnect();
    }, [roomId]); // theme is not a dependency
}

O 19.2 também adicionou cacheSignal para Server Components (ele avisa quando um resultado de cache() não é mais necessário) e as Performance Tracks no painel de performance do Chrome DevTools. O React 19.1 adicionou captureOwnerStack, uma função só de desenvolvimento que retorna quais componentes renderizaram o atual.

Server Components e Server Functions

Server Components são componentes que executam antecipadamente no servidor (ou no momento do build) e enviam o resultado para o navegador. Eles podem ser async e ler um banco de dados diretamente, e o código deles nunca vai para o cliente. Server Functions (chamadas primeiro de Server Actions) são funções assíncronas marcadas com 'use server' que um componente do cliente pode chamar como uma função comum. Os dois precisam de um framework com um bundler que os suporte, como o App Router do Next.js, então não conseguem rodar neste editor.

// A Server Component: async, runs on the server only
export default async function Notes() {
    const notes = await db.notes.findMany();
    return notes.map((note) => <Note key={note.id} note={note} />);
}

// A Server Function, usable as a form action
async function createNote(formData) {
    'use server';
    await db.notes.create({ text: formData.get('text') });
}

APIs removidas e alteradas

O React 19 removeu APIs que estavam descontinuadas havia anos:

Componentes de classe mantêm defaultProps. Os erros também são reportados de outro jeito: erros capturados por um error boundary são registrados uma vez com console.error, erros não capturados vão para window.reportError, e createRoot aceita as opções onCaughtError e onUncaughtError para você mesmo reportá-los.

Atualizando para o React 19

Atualize primeiro para o React 18.3. Ele é idêntico ao 18.2, mas avisa sobre as APIs descontinuadas e outras mudanças de que o React 19 precisa, para você corrigi-las enquanto o app ainda funciona. O React 19 também exige a transformação moderna de JSX, que o Vite e todos os frameworks atuais já usam. Depois instale o React 19:

npm install react@^19 react-dom@^19
npm install --save-dev @types/react@^19 @types/react-dom@^19

O guia oficial de atualização indica codemods para as mudanças mecânicas. O primeiro cuida de string refs, imports de act e ReactDOM.render; o segundo atualiza código TypeScript para os novos tipos:

npx codemod@latest react/19/migration-recipe
npx types-react-codemod@latest preset-19 ./src

Depois de atualizar, nada obriga você a adotar Actions ou os novos hooks. Componentes, hooks e componentes de classe existentes continuam funcionando; você pode passar os formulários para <form action> um de cada vez.