1# AngularUI Router  [![Build Status](https://travis-ci.org/angular-ui/ui-router.svg?branch=master)](https://travis-ci.org/angular-ui/ui-router)
  2
  3#### The de-facto solution to flexible routing with nested views
  4---
  5**[Download 0.2.11](http://angular-ui.github.io/ui-router/release/angular-ui-router.js)** (or **[Minified](http://angular-ui.github.io/ui-router/release/angular-ui-router.min.js)**) **|**
  6**[Guide](https://github.com/angular-ui/ui-router/wiki) |**
  7**[API](http://angular-ui.github.io/ui-router/site) |**
  8**[Sample](http://angular-ui.github.com/ui-router/sample/) ([Src](https://github.com/angular-ui/ui-router/tree/gh-pages/sample)) |**
  9**[FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions) |**
 10**[Resources](#resources) |**
 11**[Report an Issue](https://github.com/angular-ui/ui-router/blob/master/CONTRIBUTING.md#report-an-issue) |**
 12**[Contribute](https://github.com/angular-ui/ui-router/blob/master/CONTRIBUTING.md#contribute) |**
 13**[Help!](http://stackoverflow.com/questions/ask?tags=angularjs,angular-ui-router) |**
 14**[Discuss](https://groups.google.com/forum/#!categories/angular-ui/router)**
 15
 16---
 17
 18AngularUI Router is a routing framework for [AngularJS](http://angularjs.org), which allows you to organize the
 19parts of your interface into a [*state machine*](https://en.wikipedia.org/wiki/Finite-state_machine). Unlike the
 20[`$route` service](http://docs.angularjs.org/api/ngRoute.$route) in the Angular ngRoute module, which is organized around URL
 21routes, UI-Router is organized around [*states*](https://github.com/angular-ui/ui-router/wiki),
 22which may optionally have routes, as well as other behavior, attached.
 23
 24States are bound to *named*, *nested* and *parallel views*, allowing you to powerfully manage your application's interface.
 25
 26Check out the sample app: http://angular-ui.github.io/ui-router/sample/
 27
 28-
 29**Note:** *UI-Router is under active development. As such, while this library is well-tested, the API may change. Consider using it in production applications only if you're comfortable following a changelog and updating your usage accordingly.*
 30
 31
 32## Get Started
 33
 34**(1)** Get UI-Router in one of the following ways:
 35 - clone & [build](CONTRIBUTING.md#developing) this repository
 36 - [download the release](http://angular-ui.github.io/ui-router/release/angular-ui-router.js) (or [minified](http://angular-ui.github.io/ui-router/release/angular-ui-router.min.js))
 37 - via **[Bower](http://bower.io/)**: by running `$ bower install angular-ui-router` from your console
 38 - or via **[npm](https://www.npmjs.org/)**: by running `$ npm install angular-ui-router` from your console
 39 - or via **[Component](https://github.com/component/component)**: by running `$ component install angular-ui/ui-router` from your console
 40
 41**(2)** Include `angular-ui-router.js` (or `angular-ui-router.min.js`) in your `index.html`, after including Angular itself (For Component users: ignore this step)
 42
 43**(3)** Add `'ui.router'` to your main module's list of dependencies (For Component users: replace `'ui.router'` with `require('angular-ui-router')`)
 44
 45When you're done, your setup should look similar to the following:
 46
 47>
 48```html
 49<!doctype html>
 50<html ng-app="myApp">
 51<head>
 52    <script src="//ajax.googleapis.com/ajax/libs/angularjs/1.1.5/angular.min.js"></script>
 53    <script src="js/angular-ui-router.min.js"></script>
 54    <script>
 55        var myApp = angular.module('myApp', ['ui.router']);
 56        // For Component users, it should look like this:
 57        // var myApp = angular.module('myApp', [require('angular-ui-router')]);
 58    </script>
 59    ...
 60</head>
 61<body>
 62    ...
 63</body>
 64</html>
 65```
 66
 67### [Nested States & Views](http://plnkr.co/edit/u18KQc?p=preview)
 68
 69The majority of UI-Router's power is in its ability to nest states & views.
 70
 71**(1)** First, follow the [setup](#get-started) instructions detailed above.
 72
 73**(2)** Then, add a [`ui-view` directive](https://github.com/angular-ui/ui-router/wiki/Quick-Reference#ui-view) to the `<body />` of your app.
 74
 75>
 76```html
 77<!-- index.html -->
 78<body>
 79    <div ui-view></div>
 80    <!-- We'll also add some navigation: -->
 81    <a ui-sref="state1">State 1</a>
 82    <a ui-sref="state2">State 2</a>
 83</body>
 84```
 85
 86**(3)** You'll notice we also added some links with [`ui-sref` directives](https://github.com/angular-ui/ui-router/wiki/Quick-Reference#ui-sref). In addition to managing state transitions, this directive auto-generates the `href` attribute of the `<a />` element it's attached to, if the corresponding state has a URL. Next we'll add some templates. These will plug into the `ui-view` within `index.html`. Notice that they have their own `ui-view` as well! That is the key to nesting states and views.
 87
 88>
 89```html
 90<!-- partials/state1.html -->
 91<h1>State 1</h1>
 92<hr/>
 93<a ui-sref="state1.list">Show List</a>
 94<div ui-view></div>
 95```
 96```html
 97<!-- partials/state2.html -->
 98<h1>State 2</h1>
 99<hr/>
100<a ui-sref="state2.list">Show List</a>
101<div ui-view></div>
102```
103
104**(4)** Next, we'll add some child templates. *These* will get plugged into the `ui-view` of their parent state templates.
105
106>
107```html
108<!-- partials/state1.list.html -->
109<h3>List of State 1 Items</h3>
110<ul>
111  <li ng-repeat="item in items">{{ item }}</li>
112</ul>
113```
114
115>
116```html
117<!-- partials/state2.list.html -->
118<h3>List of State 2 Things</h3>
119<ul>
120  <li ng-repeat="thing in things">{{ thing }}</li>
121</ul>
122```
123
124**(5)** Finally, we'll wire it all up with `$stateProvider`. Set up your states in the module config, as in the following:
125
126
127>
128```javascript
129myApp.config(function($stateProvider, $urlRouterProvider) {
130  //
131  // For any unmatched url, redirect to /state1
132  $urlRouterProvider.otherwise("/state1");
133  //
134  // Now set up the states
135  $stateProvider
136    .state('state1', {
137      url: "/state1",
138      templateUrl: "partials/state1.html"
139    })
140    .state('state1.list', {
141      url: "/list",
142      templateUrl: "partials/state1.list.html",
143      controller: function($scope) {
144        $scope.items = ["A", "List", "Of", "Items"];
145      }
146    })
147    .state('state2', {
148      url: "/state2",
149      templateUrl: "partials/state2.html"
150    })
151    .state('state2.list', {
152      url: "/list",
153      templateUrl: "partials/state2.list.html",
154      controller: function($scope) {
155        $scope.things = ["A", "Set", "Of", "Things"];
156      }
157    });
158});
159```
160
161**(6)** See this quick start example in action.
162>**[Go to Quick Start Plunker for Nested States & Views](http://plnkr.co/edit/u18KQc?p=preview)**
163
164**(7)** This only scratches the surface
165>**[Dive Deeper!](https://github.com/angular-ui/ui-router/wiki)**
166
167
168### [Multiple & Named Views](http://plnkr.co/edit/SDOcGS?p=preview)
169
170Another great feature is the ability to have multiple `ui-view`s view per template.
171
172**Pro Tip:** *While multiple parallel views are a powerful feature, you'll often be able to manage your
173interfaces more effectively by nesting your views, and pairing those views with nested states.*
174
175**(1)** Follow the [setup](#get-started) instructions detailed above.
176
177**(2)** Add one or more `ui-view` to your app, give them names.
178>
179```html
180<!-- index.html -->
181<body>
182    <div ui-view="viewA"></div>
183    <div ui-view="viewB"></div>
184    <!-- Also a way to navigate -->
185    <a ui-sref="route1">Route 1</a>
186    <a ui-sref="route2">Route 2</a>
187</body>
188```
189
190**(3)** Set up your states in the module config:
191>
192```javascript
193myApp.config(function($stateProvider) {
194  $stateProvider
195    .state('index', {
196      url: "",
197      views: {
198        "viewA": { template: "index.viewA" },
199        "viewB": { template: "index.viewB" }
200      }
201    })
202    .state('route1', {
203      url: "/route1",
204      views: {
205        "viewA": { template: "route1.viewA" },
206        "viewB": { template: "route1.viewB" }
207      }
208    })
209    .state('route2', {
210      url: "/route2",
211      views: {
212        "viewA": { template: "route2.viewA" },
213        "viewB": { template: "route2.viewB" }
214      }
215    })
216});
217```
218
219**(4)** See this quick start example in action.
220>**[Go to Quick Start Plunker for Multiple & Named Views](http://plnkr.co/edit/SDOcGS?p=preview)**
221
222
223## Resources
224
225* [In-Depth Guide](https://github.com/angular-ui/ui-router/wiki)
226* [API Reference](http://angular-ui.github.io/ui-router/site)
227* [Sample App](http://angular-ui.github.com/ui-router/sample/) ([Source](https://github.com/angular-ui/ui-router/tree/gh-pages/sample))
228* [FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions)
229* [Slides comparing ngRoute to ui-router](http://slid.es/timkindberg/ui-router#/)
230* [UI-Router Extras / Addons](http://christopherthielen.github.io/ui-router-extras/#/home) (@christopherthielen)
231 
232### Videos
233
234* [Introduction Video](https://egghead.io/lessons/angularjs-introduction-ui-router) (egghead.io)
235* [Tim Kindberg on Angular UI-Router](https://www.youtube.com/watch?v=lBqiZSemrqg)
236* [Activating States](https://egghead.io/lessons/angularjs-ui-router-activating-states) (egghead.io)
237* [Learn Angular.js using UI-Router](http://youtu.be/QETUuZ27N0w) (LearnCode.academy)
238
239
240
241## Reporting issues and Contributing
242
243Please read our [Contributor guidelines](CONTRIBUTING.md) before reporting an issue or creating a pull request.