About States

UI-Router applications behave like a state machine.

Think about each feature of an application as a set of states. Only one state can be active at one time. The user can transition from one state to another, to activate a different feature of the application.

UI-Router States

The basic building block of a UI-Router application is a UI-Router state.
A UI-Router state usually corresponds to a feature (or place) in the application in terms of the overall UI and navigation. Some examples of states might be dashboard, messages, shoppingcart, or blogentry.

A state is a javascript object which has specific properties. Those properties define the functionality of the application when that state is active.

State Properties

name
A name for the state, providing a way to refer to the state
views
How the UI will look and behave
url
What the browser’s URL will be
params
Parameter values that the state requires (such as blog-post-id)
resolve
The actual data the state requires (often fetched, asynchronously, from the backend using a parameter value)

Nested States

Unlike states in a traditional state machine, UI-Router states can be nested inside each other. A parent state can have multiple children, forming a tree of states.

Child states can be used to drill down from a more general feature to more specific one, or to implement a master/detail pattern. For instance, you might have a parent state called contacts which defines the contacts module, and renders a list of all the contacts.

Nested views

The child state’s view usually renders inside a viewport that the parent state created. This is referred to as Nested Views

Then, you might have two child states contacts.contact (to view a specific contact’s details) and contacts.new (to create a new contact). These substates share the common parent state contacts and inherit data and behavior from the parent. They are rendered inside the UI for the parent state.

State-based approach

UI-Router’s approach to applications as a tree of states encourages you to think about your application’s as a hierarchy of functionality. The tree defines the application’s functionality structure. The URL and views (i.e., the rendered tree of components in the DOM) are artifacts of the active state.

Optional Urls

Although states generally have URLs, they are optional.

You might create some child states without URLs, if it doesn’t make sense to bookmark those child states. The state machine transitions between url-less states as usual, but does not update the url when complete You still get all the other benefits of a state transition such as parameters, resolve, and lifecycle hooks.

Optional Views

Although states generally have views, they are optional.

You might create a parent state for the sole purpose of adding data or behaviors to a branch of your application.
For instance, you might create a state called admin and then child states for each administration function in your app. The parent admin state could be used to restrict access to the entire tree of child states, but provide no UI itself.

Transitions

If the app’s current state is contacts and the user wants to switch to the prefs state, the UI-Router state machine creates and runs a Transition from the contacts state to the prefs state.

Atomic

These transitions are essentially atomic. When transitioning from contacts to prefs, either the entire transition succeeds and the application’s current state is now prefs, or the entire transition fails and the application remains in the contacts state.

Lifecycle

Transitions have a lifecycle, starting at Transition creation and completing with either success or failure. That lifecycle is exposed to the application developer as a set of transition hooks. The hooks allow you to tap into each stage of the Transition and cancel or alter the Transition.

To learn more about transition hooks, read the Transitions Guide and the in depth API documentation for TransitionService.

Updated: