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 (or view, see below)!

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 name as String

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, such as opening a dialog.

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

Learn more about state callbacks

data

Arbitrary data object, useful for custom configuration.

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 in the location bar, otherwise it will not.

$state.self

Returns State Object

A reference to the state's config object. However you passed it in. Useful for accessing custom data.

Learn More about the state config object

$state.includes(partialState)

Returns Boolean

A method to determine if the current state includes partialState.

partialState

String

A partial name to be searched for within the current state name. For example, if you had the following states set up:

• contacts
• contacts.list
• contacts.details
• contacts.details.item
• about

So, e.g. if you were within contact.details.item then:

• $state.includes("contact"); // returns true
• $state.includes("contact.details"); // returns true
• $state.includes("contact.details.item"); // returns true
• $state.includes("contact.list"); // returns false
• $state.includes("about"); // returns false

$state.is(stateOrName)

Returns Boolean

Similar to includes, but only checks for the full state name.

partialState

String or Object State Object

So, e.g. if you were within contact.details.item then:

$state.is("contact.details.item"); // returns true
$state.is(contactDetailItemStateConfigObj); // returns true
// Everything else would return false

$state.href(stateOrName, params)

Returns String Compiled URL

A url generation method that returns the compiled url for the given state populated with the given params.

e.g. expect($state.href("about.person", { person: "bob" })).toEqual("/about/bob");

stateOrName

String or Object

The state name or state object you'd like to generate a url from.

params

Object

An object of parameter values to fill the state's required parameters.

Note: About using $state within a template

Since its very common to access $state in your templates, you need to bind $state to $rootScope (or any other accessible scope) to access it from a template/view. Typically you can do this on module run:

angular.module("myApp").run(function ($rootScope, $state, $stateParams) {
    $rootScope.$state = $state;
    $rootScope.$stateParams = $stateParams;
});

Now you can access state within a template:

<ul class="nav">
    <li ng-class="{ active: $state.includes('contacts') }"><a href="#/contacts">Contacts</a></li>
    <li ng-class="{ active: $state.includes('about') }"><a href="#/about">About</a></li>
</ul>

$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

Directives

The following directives are provided by the ui.state module.

ui-view

The ui-view directive tells $state where to place your templates. A view can be unnamed or named.

<!-- Unnamed -->
<div ui-view></div> 

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

You can only have one unnamed view within any template (or root html). If you are only using a single view and it is unnamed then you can populate it like so:

<div ui-view></div> 

$stateProvider.state("home", {
    template: "<h1>HELLO!</h1>"
})

The above is equivalent to specifying your view explicity, by name, in this case an empty name:

$stateProvider.state("home", {
    views: {
        "": {
            template: "<h1>HELLO!</h1>"
        }
    }    
})

But typically you'll only use the views property if you name your view or have more than one view in the same template. There's not really a compelling reason to name a view if its the only one, but you could if you wanted, like so:

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

$stateProvider.state("home", {
    views: {
        "main": {
            template: "<h1>HELLO!</h1>"
        }
    }    
})

Really though, you'll use views to set up multiple views:

<div ui-view></div>
<div ui-view="chart"></div> 
<div ui-view="data"></div> 

$stateProvider.state("home", {
    views: {
        "": {
            template: "<h1>HELLO!</h1>"
        },
        "chart": {
            template: "<chart_thing/>"
        },
        "data": {
            template: "<data_thing/>"
        }
    }    
})

ui-sref

A directive that binds a link to a given state. If the state has an associated URL, the directive will automatically generate & update the href attribute. Clicking the link will trigger a state transition with optional parameters. Examples:

<a ui-sref="home">Home</a> | <a ui-sref="about">About</a>

<ul>
    <li ng-repeat="contact in contacts">
        <a ui-sref="contacts.view({ id: contact.id })">{{ contact.name }}</a>
    </li>
</ul>

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)

ANYTHING MISSING? Please add it to this list to be documented. I want this to reflect the full API!