Referencia

useTransition()

Llama a useTransition en el nivel superior de tu componente para marcar algunas actualizaciones de estado como Transiciones.

Parámetros

useTransition no recibe ningun parámetro.

Devuelve

useTransition devuelve un array con exactamente dos elementos:

  1. isPending que indica si hay una Transición pendiente.
  2. que permite marcar actualizaciones como una Transición.

Función startTransition

La función startTransition devuelta por useTransition permite marcar una actualización de estado como una Transición.

Parameters

  • action: A function that updates some state by calling one or more . React calls action immediately with no parameters and marks all state updates scheduled synchronously during the action function call as Transitions. Any async calls that are awaited in the action will be included in the Transition, but currently require wrapping any set functions after the await in an additional startTransition (see ). State updates marked as Transitions will be and .

Devuelve

startTransition no devuelve nada.

Advertencias

  • useTransition es un Hook, por lo que sólo puede ser llamado dentro de componentes o Hooks personalizados. Si necesitas iniciar una Transición en otro lugar (por ejemplo, desde una biblioteca de datos), llama a la función independiente en su lugar.

  • Puedes envolver una actualización en una Transición sólo si tienes acceso a la función set de ese estado. Si deseas iniciar una Transición en respuesta a alguna prop o algún valor de un Hook personalizado, prueba en su lugar.

  • The function you pass to startTransition is called immediately, marking all state updates that happen while it executes as Transitions. If you try to perform state updates in a setTimeout, for example, they won’t be marked as Transitions.

  • You must wrap any state updates after any async requests in another startTransition to mark them as Transitions. This is a known limitation that we will fix in the future (see ).

  • La función startTransition tiene una identidad estable, por lo que a menudo verás que se omite de las dependencias de los Efectos, pero que se incluya no causa que el Efecto se dispare. Si el linter te permite omitir una dependencia sin errores, es seguro hacerlo.

  • Una actualización de estado marcada como Transición será interrumpida por otras actualizaciones de estado. Por ejemplo, si actualizas un componente gráfico dentro de una Transición, pero luego empiezas a escribir en un input mientras el gráfico está en medio de un rerenderizado, React reiniciará el trabajo de renderizado en el componente gráfico después de gestionar la actualización del input.

  • Las actualizaciones de Transición no pueden utilizarse para controlar las entradas de texto.

  • Si hay varias Transiciones en curso, React las agrupa. Se trata de una limitación que podría eliminarse en una versión futura.

Uso

Perform non-blocking updates with Actions

Call useTransition at the top of your component to create Actions, and access the pending state:

useTransition devuelve un array con exactamente dos elementos:

  1. isPending flag que te indica si hay una Transición pendiente.
  2. startTransition function que te permite crear una Acción.

Para iniciar una Transición pasa una función a startTransition de esta manera:

The function passed to startTransition is called the “Action”. You can update state and (optionally) perform side effects within an Action, and the work will be done in the background without blocking user interactions on the page. A Transition can include multiple Actions, and while a Transition is in progress, your UI stays responsive. For example, if the user clicks a tab but then changes their mind and clicks another tab, the second click will be immediately handled without waiting for the first update to finish.

To give the user feedback about in-progress Transitions, to isPending state switches to true at the first call to startTransition, and stays true until all Actions complete and the final state is shown to the user. Transitions ensure side effects in Actions to complete in order to , and you can provide immediate feedback while the Transition is in progress with useOptimistic.

Exposing action prop from components

You can expose an action prop from a component to allow a parent to call an Action.

For example, this TabButton component wraps its onClick logic in an action prop:

Because the parent component updates its state inside the action, that state update gets marked as a Transition. This means you can click on “Posts” and then immediately click “Contact” and it does not block user interactions:

Displaying a pending visual state

Puedes utilizar el valor booleano isPending devuelto por useTransition para indicar al usuario que una Transición está en curso. Por ejemplo, el botón de la pestaña puede tener un estado visual especial “pendiente”:

Fíjate en que hacer clic en “Posts” ahora es más sensible porque el botón de la pestaña se actualiza inmediatamente:

Evitar indicadores de carga no deseados

In this example, the PostsTab component fetches some data using . When you click the “Posts” tab, the PostsTab component suspends, causing the closest loading fallback to appear:

Hiding the entire tab container to show a loading indicator leads to a jarring user experience. If you add useTransition to TabButton, you can instead display the pending state in the tab button instead.

Observa que al hacer clic en “Entradas” ya no se sustituye todo el contenedor de la pestaña por un spinner:

Construir un enrutador preparado para Suspense

Si estás construyendo un framework de React o un enrutador, te recomendamos marcar las navegaciones de página como Transiciones.

This is recommended for three reasons:

  • which lets the user click away without waiting for the re-render to complete.
  • which lets the user avoid jarring jumps on navigation.
  • which lets the user wait for side effects to complete before the new page is shown.

Here is a simplified router example using Transitions for navigations.

Displaying an error to users with an error boundary

If a function passed to startTransition throws an error, you can display an error to your user with an . To use an error boundary, wrap the component where you are calling the useTransition in an error boundary. Once the function passed to startTransition errors, the fallback for the error boundary will be displayed.

Solución de problemas

No funciona la actualización de una entrada en una Transición

No se puede utilizar una Transición para una variable de estado que controla una entrada:

Esto se debe a que las Transiciones son no bloqueantes, pero la actualización de una entrada en respuesta al evento de cambio debe producirse de forma sincrónica. Si deseas ejecutar una Transición en respuesta a la escritura, tiene dos opciones:

  1. Puedes declarar dos variables de estado separadas: una para el estado de la entrada (que siempre se actualiza de forma sincrónica), y otra que actualizarás en una Transición. Esto te permite controlar la entrada utilizando el estado síncrono, y pasar la variable de estado de Transición (que “irá por detrás” de la entrada) al resto de tu lógica de renderizado.
  2. Alternativamente, puedes tener una variable de estado, y añadir que “irá por detrás” del valor real. Se activarán rerenderizados no bloqueantes para “ponerse al día” con el nuevo valor de forma automática.

React no trata mi actualización de estado como una Transición

Cuando envuelvas una actualización de estado en una Transición, asegúrate de que ocurre durante la llamada startTransition:

The function you pass to startTransition must be synchronous. You can’t mark an update as a Transition like this:

En su lugar, podrías hacer esto:

React doesn’t treat my state update after await as a Transition

When you use await inside a startTransition function, the state updates that happen after the await are not marked as Transitions. You must wrap state updates after each await in a startTransition call:

Sin embargo, esto funciona en su lugar:

This is a JavaScript limitation due to React losing the scope of the async context. In the future, when is available, this limitation will be removed.

Quiero llamar a useTransition desde fuera de un componente

No puedes llamar a useTransition fuera de un componente porque es un Hook. En este caso, utiliza el método independiente . Funciona de la misma manera, pero no proporciona el indicador isPending.

La función que paso a startTransition se ejecuta inmediatamente

Si ejecutas este código, imprimirá 1, 2, 3:

Se espera que imprima 1, 2, 3. La función que pasas a startTransition no se retrasa. Al contrario que con el setTimeout del navegador, no ejecuta el callback más tarde. React ejecuta tu función inmediatamente, pero cualquier actualización de estado programada mientras se está ejecutando se marca como Transición. Puedes imaginar que funciona así:

My state updates in Transitions are out of order

If you await inside startTransition, you might see the updates happen out of order.

In this example, the updateQuantity function simulates a request to the server to update the item’s quantity in the cart. This function artificially returns the every other request after the previous to simulate race conditions for network requests.

Try updating the quantity once, then update it quickly multiple times. You might see the incorrect total:

When clicking multiple times, it’s possible for previous requests to finish after later requests. When this happens, React currently has no way to know the intended order. This is because the updates are scheduled asynchronously, and React loses context of the order across the async boundary.

This is expected, because Actions within a Transition do not guarantee execution order. For common use cases, React provides higher-level abstractions like and that handle ordering for you. For advanced use cases, you’ll need to implement your own queuing and abort logic to handle this.