Skip to main content

​
What is UI-Router Core?

UI-Router Core is a powerful, framework-agnostic routing library for JavaScript Single Page Applications (SPAs). It provides a state-based approach to routing that goes beyond simple URL matching, offering a complete state machine to manage transitions between application states.
UI-Router Core is the foundation for framework-specific implementations including UI-Router for Angular 1, UI-Router for Angular 2+, and UI-Router for React.

​
Why UI-Router Core?

Unlike traditional routers that simply map URLs to components, UI-Router models your application as a hierarchical tree of states. Each state represents a place in your application with its own URL, data requirements, and UI components.

​
Key Benefits

State-based routing

Model your application as a tree of named states rather than just URL patterns

Framework agnostic

Use the same routing core across Angular, React, Vue, or vanilla JavaScript

Powerful transitions

Transaction-like state transitions with lifecycle hooks and async support

Flexible URLs

Support for path, query, and hash parameters with custom encoding/decoding

​
Core Features

​
Hierarchical State Machine

UI-Router uses a state machine to manage transitions between application states. States can be nested, allowing you to build complex application structures with inherited properties. 
router.stateRegistry.register({
  name: 'app',
  abstract: true,
  component: AppLayout
});

router.stateRegistry.register({
  name: 'app.dashboard',
  url: '/dashboard',
  component: DashboardComponent
});

​
Named State Addressing

Navigate using state names rather than URLs, with support for both absolute and relative addressing:
  • Absolute: admin.users
  • Relative: .users (from current state)

​
Multiple Named Views

Define multiple UI regions that can be independently controlled: 
router.stateRegistry.register({
  name: 'home',
  url: '/',
  views: {
    header: { component: HeaderComponent },
    content: { component: HomeComponent },
    sidebar: { component: SidebarComponent }
  }
});

​
Typed Parameters

UI-Router supports typed URL parameters with built-in types and the ability to define custom parameter types:
  • Built-in types: int, string, date, json, bool, path, query, hash
  • Optional or required parameters
  • Default values with URL squashing
  • Custom encoding/decoding
router.stateRegistry.register({
  name: 'user',
  url: '/user/{userId:int}',
  params: {
    userId: { type: 'int' },
    showDetails: { value: false, squash: true }
  }
});

​
Resolve - Async Data Fetching

Fetch data asynchronously before entering a state, with dependency injection support: 
router.stateRegistry.register({
  name: 'user',
  url: '/user/:userId',
  resolve: [
    {
      token: 'user',
      deps: ['UserService', Transition],
      resolveFn: (userService, trans) => {
        return userService.getUser(trans.params().userId);
      }
    }
  ]
});

​
Transition Lifecycle Hooks

Attach behavior at any point during a state transition: 
// Global hook for all transitions
router.transitionService.onStart({}, (transition) => {
  console.log('Transition started from', transition.from().name);
});

// Hook for specific state criteria
router.transitionService.onEnter({ entering: 'admin.**' }, (transition, state) => {
  return checkAuthentication();
});
Available hook types:
  • onBefore - Before the transition starts
  • onStart - As the transition starts
  • onEnter - When entering a state
  • onRetain - When a state is retained (not exited/entered)
  • onExit - When exiting a state
  • onFinish - After the transition succeeds
  • onSuccess - Alias for onFinish
  • onError - When transition fails

​
Framework Agnostic Design

UI-Router Core is designed to work with any JavaScript framework or none at all. It provides the core routing logic while framework-specific adapters handle the integration: 
import { UIRouter } from '@uirouter/core';
import { pushStateLocationPlugin } from '@uirouter/core';

const router = new UIRouter();
router.plugin(pushStateLocationPlugin);

​
Architecture Overview

The UIRouter class provides access to all core services: 
const router = new UIRouter();

// State management
router.stateRegistry  // Register and manage states
router.stateService   // Navigate between states

// URL management  
router.urlService     // URL routing and synchronization

// Transition management
router.transitionService  // Transition lifecycle hooks

// Global state
router.globals        // Current state and params

// View management
router.viewService    // UI-View synchronization

​
Use Cases

UI-Router Core excels at:
Build applications with deeply nested routes, multiple views, and complex navigation patterns. The hierarchical state structure naturally maps to complex UI layouts.
Since UI-Router Core is framework-agnostic, you can maintain consistent routing logic when migrating between frameworks or supporting multiple frameworks.
Use UI-Router Core as the foundation for building custom routers for new frameworks or specialized use cases. Implement UIView, UISref, and framework-specific bootstrapping.
Leverage resolve dependencies to fetch data before rendering views, ensuring your components always have the data they need.

​
Next Steps

Ready to get started? Follow our installation and quickstart guides:

Installation

Install UI-Router Core in your project

Quickstart

Build your first router in minutes

Core Concepts

Learn about states, transitions, and URLs

API Reference

Explore the complete API documentation

​
Community and Support

GitHub

Report issues and contribute to the project

Stack Overflow

Get help from the community

Build docs developers (and LLMs) love

Get started for freeTalk to us