Guide · Open source
How to use ui-router: setup, states and nested views
Updated · written with AI from the project's own documentation and checked against our catalogue data
UI-Router is a client-side routing framework for AngularJS, the 1.x version of Angular. It keeps the browser URL in sync with what your single-page app shows, so users can bookmark a page deep inside the app. This guide explains the core ideas, what you need before starting, and when a different router is a better fit.
UI-Routerangular-ui/ui-router · ★ 13.4k · MIT Install options & downloads Quick start
- 1Confirm your stack. Check that your project is an AngularJS 1.x application. If it is a new Angular or React project, choose the matching UI-Router version instead.
- 2Get the source. Clone the repository with git clone https://github.com/angular-ui/ui-router, as the README instructs.
- 3Read the official guide. Use the Angular 1 guide and tutorials linked from the README to learn the state syntax.
- 4Model your app as states. Give each screen a named state and nest child states under their parent layouts.
- 5Add nested views. Render child states inside parent layouts so the screen follows the URL.
- 6Test deep links. Open a deep URL directly in the browser to confirm the right state loads and can be bookmarked.
What UI-Router does
Routing frameworks for single-page applications update the browser's URL as the user navigates. UI-Router works in the other direction too: changes to the URL can drive navigation through the app. That is what lets a user create a bookmark to a location deep within the app.
UI-Router models an application as a hierarchical tree of named states. It provides a state machine that manages transitions between those states in a transaction-like manner.
Check that UI-Router fits your project
The README says this package is the source for UI-Router version 1.x and targets AngularJS specifically. It points newer work to separate UI-Router versions for Angular 2 and React. If you are starting a new project, look at those versions instead.
The source also says the 0.x line lives on a separate legacy branch. If your app still uses 0.x, you need that branch rather than this one.
- Good fit: an existing AngularJS 1.x application that needs nested views following URL structure.
- Good fit: apps where deep-linkable, bookmarkable pages matter.
- Not a fit: new projects (use the Angular or React UI-Router versions).
- Not a fit: non-developers, since it is a code library with no standalone interface.
Get the source code
The README's install instruction is to clone the repository. Your application must already be an AngularJS 1.x application. The README does not describe a package-manager install step, so follow the official guide linked from the README for loading the library into your project.
git clone https://github.com/angular-ui/ui-routerDefine your states as a tree
Each page or screen in the app is a named state. States nest inside each other, so a child state sits under a parent. The URL structure can follow that tree, which is why nested views and deep links work together.
The README links to an in-depth guide and tutorials on the project homepage for the exact state definition syntax. Use those as the reference for code examples.
- Give every state a unique name.
- Nest child states under the parent that owns their layout.
- Let the URL reflect the state so the page can be bookmarked.
Use nested views for layouts
Nested views follow URL structure: a parent state can render a layout, and child states fill a part of that layout as the URL changes. This is the main reason teams choose UI-Router over simpler routing.
Learn the common pitfalls
Before you build on UI-Router, read the project's Frequently Asked Questions wiki and the Contributor guidelines. The README asks contributors to read the guidelines before reporting an issue or opening a pull request.
If you get stuck, the README links a Stack Overflow tag for angularjs and angular-ui-router questions.
What people use it for
- Keeping a deep product or account page bookmarkable inside an AngularJS app.
- Building a dashboard layout where a parent view stays fixed and child views change with the URL.
- Maintaining an existing AngularJS 1.x app that already uses nested states.
- Moving between app screens as a managed state machine rather than ad hoc navigation code.
Frequently asked questions
Is ui-router free to use?
The repository is licensed under MIT. Check the LICENSE file in the repository for the full terms before you use it in a project.
What are the requirements for ui-router?
The stated prerequisite is an AngularJS 1.x application. The package targets AngularJS specifically, so it does not apply to new Angular or React projects.
How do I install ui-router?
The README gives one install command: git clone https://github.com/angular-ui/ui-router. Follow the official Angular 1 guide linked from the README to load it into your app.
Is ui-router the same as ngRoute?
No. The README links a slide deck comparing ngRoute to ui-router. The main difference the project emphasizes is nested views and a state machine, while ngRoute is the simpler router that ships with AngularJS.
Should I use ui-router for a new Angular project?
Probably not. The README points newer work to separate UI-Router versions for Angular 2 and React, and this 1.x package targets AngularJS specifically. Angular's own router is the other option to compare.
My app still uses ui-router 0.x. What should I do?
The README says the 0.x source lives on a separate legacy branch. Use that branch for your existing app, or plan a migration to 1.x.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use UI-Router if you maintain an AngularJS 1.x application and need nested views and bookmarkable deep links. Pick something else for new Angular or React projects, or if you need a non-code tool, since this is a library with no standalone interface.
Install options & downloads