Quick Reference

Configure your states in your module's config method.

Be sure to include ui.state as a module dependency.

angular.module("myApp", [ui.state]).config(["$stateProvider", function($stateProvider){
	$stateProvider.state(stateName, stateConfig);
}])

$stateProvider

.state(stateName, stateConfig)

Creates a new application state. For alternate usage, see Object-based States

The parameters for .state() are:

stateName

String

A unique state name, e.g. "home", "about", "contacts". To create a parent/child state use a dot, e.g. "about.sales", "home.newest". Read more about nested states: Nested States & Nested Views

// The state() method takes a unique stateName (String) and a stateConfig (Object)
$stateProvider.state(stateName, stateConfig);

// stateName can be a single top-level name (must be unique).
$stateProvider.state("home", {});

// Or it can be a nested state name. This state is a child of the above "home" state.
$stateProvider.state("home.newest", {});

// Nest states as deeply as needed.
$stateProvider.state("home.newest.abc.xyz.inception", {});

// state() returns $stateProvider, so you can chain state declarations.
$stateProvider.state("home", {}).state("about", {}).state("contacts", {});

stateConfig

Object

The stateConfig object has the following acceptable properties. This is just a reference, for usage and details please click the "Learn more..." links.

template, templateURL, templateProvider

Three ways to set up your templates. Only use one per state!

template String HTML content

templateURL String URL path to template file OR Function, returns URL path string

templateProvider Function, returns HTML content string

Learn more about state templates

controller

A controller paired to the state

controller Function OR String service name

Learn more about controllers

resolve

A map of dependencies which should be injected into the controller

resolve Object

• keys - name of dependency to be injected into controller
• factory - {string|function} If string then it is alias for service. Otherwise if function, it is injected and return value it treated as dependency. If result is a promise, it is resolved before its value is injected into controller

Learn more about resolve

url

A url with optional parameters. When a state is navigated or transitioned to, the $stateParams service will be populated with any parameters that were passed.

url String

Learn more about url routing with states

params

An array of parameter names or regular expressions. Only use this within a state if you are not using url. Otherwise you can specify your parameters within the url. When a state is navigated or transitioned to, the $stateParams service will be populated with any parameters that were passed.

params Array

Learn more about parameters (examples are shown in url form, but they work just the same here)

views

Use the views property to set up multiple views. If you don't need multiple views within a single state this property is not needed. Tip: remember that often nested views are more useful and powerful than multiple sibling views.

views Object

• keys - {string} name of ui-view
• view config - {object} view configuration object can set up its own templates, controllers and resolve data.

Learn more about multiple named views

abstract

An abstract state will never be directly activated, but can provide inherited properties to its common children states.

abstract Boolean - (default is false)

Learn more about abstract states

onEnter, onExit

Callback functions for when a state is entered and exited. Good way to trigger an action or dispatch an event.

onEnter Function, injected including resolves onExit Function, injected including resolves

Learn more about state callbacks

data

Arbitrary data object, useful for custom data.

data Object

Learn more about attaching custom data to states

$state

transitionTo(to, toParams, updateLocation)

Transitions to a new state. Useful as a programmatic way to transition between states.

to

String

The name of the state that will be transitioned to.

toParams

Object

A map of the parameters that will be sent to the state, will populate $stateParams.

updateLocation

Boolean (defaults to true)

If true (default) it will update the url location, otherwise it will not.

$stateParams

A service that is populated by the current state's parameters. Useful for injecting into your own controllers or services to access the parameters. It will have one key per url parameter.

Learn more about $stateParams

---

STILL TO DO

The following need to be written up in Quick Reference format

Section for Directives related to state

subsection for ui-view

<div ui-view></div>
<div ui-view="viewName"></div>

subsection for ui-sref

<div ui-sref></div>

Need to move these up to $state section and document them

• $state.self
• $state.includes()
• $state.current
• $state.href()

Section for events

State Change Events

All these events are fired at the $rootScope level.

• $stateChangeSuccess - fired once the state transition is complete.
• $stateChangeStart - fired when the transition begins.
• $stateChangeError - fired when an error occurs during transition.
• $viewContentLoaded - fired once per view when the view is loaded (after DOM is rendered)