Transitions

This guide provides a conceptual overview to state transitions in UI-Router.


Transition overview

UI-Router applications behave like a state machine. Each part of the application (i.e., each route or page) is represented by an application state. Only one state can be active at a time. The user changes the active state by following links, clicking on buttons, using the back button, etc.

Switching between "Hello" and "About" states by clicking links. The state visualizer (right) shows the active state.

The process of changing application states is called a Transition. The state machine transitions from one state to another.

From state/to state

Each Transition has a from state (the state that was previously active) and a to state (the state being activated).

Clicking the 'About' link starts a transition _from_ the 'hello' state _to_ the 'about' state.

UI-Router provides a Transition object which represents a transition. Access the to and from states using Transition.to() and Transition.from().

Exiting and entering

During the transition from ‘Hello’ to ‘About’, the ‘Hello’ state is exited, and the ‘About’ state is entered.

The transition exits 'Hello' and enters 'About'.

Access the entering and exiting states using Transition.entering() and Transition.exiting().

Exiting or entering a state is a lifecycle event and will be covered later.

Param value changes

A transition also occurs when a parameter value changes, even if the to and from states are the same. Each parameter is defined on a specific state. When a state’s parameter value changes, the state is exited and then re-entered.

When the 'jane' link is clicked, the Transition exits the 'person' state then re-enters the 'person' state with the `name` parameter value equal to `jane`.

Access the new and previous parameter values using Transition.params('to') and Transition.params('from').

Nested states

Applications aren’t limited to a flat list of states. Instead, they often define child states creating a hierarchy of nested states.

When a parent state is active and the user navigates to a child state, a Transition from the parent state to the child starts. Because the parent state was already entered, it is not entered a second time. Instead, the parent state is retained (it was previously entered and is still entered). The child state then becomes the active state.

When the link is clicked, a Transition from 'people' to the nested 'person' state starts. The transition enters the 'person' state. The 'people' state is retained.

If the child state is active, and the user navigates to the parent state, a Transition occurs from the child to the parent state. The child state is exited and the parent state becomes the active state. Because the parent state was already entered, it is retained (not entered a second time).

The active state moves between 'people' and 'person'. The parent state ('people') is retained, while the child state ('person') is entered and exited.

Access the retained states using Transition.retained().

A single Transition may enter (or exit) multiple nested states. If the “to state” of the Transition is a nested state whose parent is not already active, then:

  • The parent is entered
  • The child (the to state) is entered
  • The child (the to state) becomes the active state

In the same way, when a transition from the nested child state to a sibling of the parent state occurs:

  • The child is exited
  • The parent is exited
  • The sibling of the parent (the to state) is entered
  • The sibling of the parent becomes the active state
Multiple states being entered or exited during each Transition

Transition Triggers

A transition occurs any time the application state changes, or when any parameter values change. This could be triggered in a variety of ways:

  • A UISref link was clicked
  • StateService.go() was called programmatically
  • The URL changed
    • The application has just started, and the initial URL is being processed
    • The back or forward button was clicked
    • The user manually changed the URL in the browser location bar
    • (In some cases) an anchor tag with an href was clicked

Transition Lifecycle

A transition can perform asynchronous asynchronous operations such as fetching data or accessing back-end APIs. Because of this, a transition should be considered a long running operation.

Lifecycle events

A transition has lifecycle events, from creation to completion. Those events are:

  • Create: The transition is being created
  • Before: The transition is about to start
  • Start: The transition has started
  • Exit: (state events) Any exiting states are exited
  • Retain: (state events) Any retained states are retained
  • Enter: (state events) Any entering states are entered
  • Finish: The transition is about to finish
  • Success/Error: The transition is finished and is either successful or errored.
The lifecycle of a Transition

Atomicity

Transitions between states should be considered atomic. A transition will either fully succeed, or fail entirely.

Although transitions may take a long time to process, the current state remains unchanged until after the transition succeeds.

Transition from state 'A' to 'B'

If a transition from state ‘A’ to state ‘B’ errors, the current state remains unchanged as state ‘A’.

Failed Transition from state 'A' to 'B'

Only one transition can run at a time. If a previous transition is still running when a new transition starts, the router aborts the previous transition. The new transition supersedes the previous transition. The previous transition errors with a Transition Superseded error.

Transition #2 supersedes Transition #1

If a transition to the current state and parameters is attempted, the router ignores the transition attempt. This might happen, e.g., when the user clicks a link to the currently activated state.

Transition to current state ignored

If a transition is running and another transition to the same target state and parameters is attempted, the router ignores the second attempt. This might happen, e.g., when the user clicks a link twice, but the first transition has not yet completed.

Duplicate transition ignored

Transition Hooks

Transition hooks allow you to tap into each of the lifecycle events using callbacks. Learn more in the Transition Hooks guide.