Skip to main content

UI-Router Core Architecture

UI-Router Core provides a state-based routing framework built around several key architectural components that work together to manage application navigation and state.

Core Components

The UIRouter class is the main entry point and container for all routing services:
export class UIRouter {
  /** Provides services related to ui-view synchronization */
  viewService = new ViewService(this);

  /** An object that contains global router state, such as the current state and params */
  globals: UIRouterGlobals = new UIRouterGlobals();

  /** A service that exposes global Transition Hooks */
  transitionService: TransitionService = new TransitionService(this);

  /** Provides services related to the URL */
  urlService: UrlService = new UrlService(this);

  /** Provides a registry for states, and related registration services */
  stateRegistry: StateRegistry = new StateRegistry(this);

  /** Provides services related to states */
  stateService = new StateService(this);
}

Key Services

State Registry

Manages state registration and hierarchy

State Service

API for state transitions and queries

Transition Service

Manages state transition lifecycle and hooks

URL Service

Handles URL routing and synchronization

View Service

Pairs ui-view components with view configurations

Architectural Principles

State-Based Routing

UI-Router uses states instead of URLs as the primary routing mechanism. States can:
  • Have URLs (optional)
  • Nest hierarchically
  • Define views, resolves, and parameters
  • Be abstract (non-navigable placeholders)

State Tree

States are organized in a hierarchical tree structure. Each state:
  • Has a unique name (e.g., "home", "users.detail")
  • Can have a parent state (implicit from name or explicit)
  • Inherits properties from parent states
See State Tree for details.

Transitions

A transition represents movement from one state to another. During a transition:
  1. States are exited (leaving current states)
  2. States are retained (staying active)
  3. States are entered (activating new states)
See Transitions for details.

Hierarchical Views

Views can be nested inside other views, creating a hierarchical component structure that mirrors the state tree. See Views for details.

Data Flow

Typical Navigation Flow

  1. Navigation trigger - User action, URL change, or API call
  2. Target state creation - StateService creates a TargetState
  3. Transition creation - TransitionService creates a Transition
  4. Hook execution - Transition hooks run in phases (onBefore, onStart, onEnter, etc.)
  5. Resolve fetching - Asynchronous data is fetched
  6. State activation - States are entered/exited
  7. View synchronization - ViewService updates ui-view components
  8. Completion - Transition promise resolves

State Lifecycle

StateObject Structure

States are represented internally as StateObject instances:
export class StateObject {
  /** The parent StateObject */
  public parent: StateObject;
  
  /** The name used to register the state */
  public name: string;
  
  /** A compiled URLMatcher which detects when the state's URL is matched */
  public url: UrlMatcher;
  
  /** The parameters for the state, built from the URL and params declaration */
  public params: { [key: string]: Param };
  
  /** The views for the state */
  public views: { [key: string]: _ViewDeclaration };
  
  /** A list of Resolvable objects. The internal representation of resolve */
  public resolvables: Resolvable[];
}

Registration

States are registered with the StateRegistry:
const state = {
  name: 'users',
  url: '/users',
  component: UsersComponent,
  resolve: {
    users: (UserService) => UserService.list()
  }
};

router.stateRegistry.register(state);

URL Management

The UrlService manages:
  • URL synchronization with the browser
  • URL rule matching
  • Parameter encoding/decoding
  • URL generation from states

Plugin System

UI-Router supports plugins to extend functionality:
class MyPlugin implements UIRouterPlugin {
  name = 'myPlugin';
  
  constructor(router: UIRouter, options: any) {
    router.transitionService.onStart({}, (trans) => {
      // Custom logic
    });
  }
}

router.plugin(MyPlugin);

Next Steps

States

Learn about state declarations and configuration

State Tree

Understand hierarchical state organization

Transitions

Explore the transition lifecycle

Hooks

Hook into the transition lifecycle

Build docs developers (and LLMs) love