The de-facto solution to flexible routing with nested views
AngularUI Router is a routing framework for AngularJS, which allows you to organize the
parts of your interface into a state machine. Unlike the
$route service in Angular core, which is organized around URL
routes, UI-Router is organized around states,
which may optionally have routes, as well as other behavior, attached.
States are bound to named, nested and parallel views, allowing you to powerfully manage your application's interface.
Warning: UI-Router is pre-beta and under active development. As such, while this library is well-tested, the API is subject to change. Using it in a project that requires guaranteed stability is not recommended.
(1) Get UI-Router in one of 4 ways:
- clone & build this repository
- download the release (or minified)
- via Bower: by running
$ bower install angular-ui-router from your console
- or via Component: by running
$ component install angular-ui/ui-router from your console
angular-ui-router.min.js) in your
index.html, after including Angular itself (For Component users: ignore this step)
'ui.router' to your main module's list of dependencies (For Component users: replace
When you're done, your setup should look similar to the following:
Nested States & Views
The majority of UI-Router's power is in its ability to nest states & views.
(1) First, follow the setup instructions detailed above.
(2) Then, add a
ui-view directive to the
<body /> of your app.
(3) You'll notice we also added some links with
ui-sref directives. 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
index.html. Notice that they have their own
ui-view as well! That is the key to nesting states and views.
(4) Next, we'll add some child templates. These will get plugged into the
ui-view of their parent state templates.
(5) Finally, we'll wire it all up with
$stateProvider. Set up your states in the module config, as in the following:
(6) See this quick start example in action.
(7) This only scratches the surface
Multiple & Named Views
Another great feature is the ability to have multiple
ui-views view per template.
Pro Tip: While mulitple parallel views are a powerful feature, you'll often be able to manage your interfaces more effectively by nesting your views, and pairing those views with nested states.
(1) Follow the setup instructions detailed above.
(2) Add one or more
ui-view to your app, give them names.
(3) Set up your states in the module config:
(4) See this quick start example in action.
Report an Issue
Help us make UI-Router better! If you think you might have found a bug, or some other weirdness, start by making sure it hasn't already been reported. You can search through existing issues to see if someone's reported one similar to yours.
If not, then create a plunkr that demonstrates the problem (try to use as little code as possible: the more minimalist, the faster we can debug it).
Next, create a new issue that briefly explains the problem, and provides a bit of background as to the circumstances that triggered it. Don't forget to include the link to that plunkr you created!
Finally, if you're unsure how a feature is used, or are encountering some unexpected behavior that you aren't sure is a bug, it's best to talk it out in the Google Group or on StackOverflow before reporting it. This keeps development streamlined, and helps us focus on building great software.
(1) See the Developing section below, to get the development version of UI-Router up and running on your local machine.
(2) Check out the roadmap to see where the project is headed, and if your feature idea fits with where we're headded.
(3) If you're not sure, open an RFC to get some feedback on your idea.
(4) Finally, commit some code and open a pull request. Code & commits should abide by the following rules:
- Always have test coverage for new features (or regression tests for bug fixes), and never break existing tests
- Commits should represent one logical change each; if a feature goes through multiple iterations, squash your commits down to one
- Changes should always respect the coding style of the project
UI-Router uses grunt >= 0.4.x. Make sure to upgrade your environment and read the Migration Guide.
Dependencies for building from source and running tests:
- grunt-cli - run:
$ npm install -g grunt-cli
- Then, install the development dependencies by running
$ npm installfrom the project directory
There are a number of targets in the gruntfile that are used to generating different builds:
grunt: Perform a normal build, runs jshint and karma tests
grunt build: Perform a normal build
grunt dist: Perform a clean build and generate documentation
grunt dev: Run dev server (sample app) and watch for changes, builds and runs karma tests on changes.