Skip to main content

​
Package Installation

Install UI-Router Core using your preferred package manager: 
npm install @uirouter/core
UI-Router Core requires Node.js version 4.0.0 or higher.

​
Package Contents

The @uirouter/core package includes multiple build formats to support different module systems and use cases:

​
Module Formats

import { UIRouter } from '@uirouter/core';
// Uses: lib/index.js

​
TypeScript Support

UI-Router Core is written in TypeScript and includes full type definitions:
package.json
{
  "typings": "lib/index.d.ts",
  "main": "lib/index.js",
  "module": "lib-esm/index.js"
}
Type definitions are automatically available when you install the package. No additional @types package is needed.

​
TypeScript Configuration

If you’re using TypeScript, ensure your tsconfig.json includes these settings:
tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "lib": ["es2015", "dom"],
    "target": "es5",
    "module": "commonjs"
  }
}
UI-Router Core supports TypeScript 3.9 and later. The package includes downleveled type definitions for compatibility.

​
Basic Setup

After installation, import and create a UIRouter instance:
1

Import UIRouter

Import the UIRouter class from the package:
import { UIRouter } from '@uirouter/core';
2

Create router instance

Instantiate the UIRouter class:
const router = new UIRouter();
The basic UIRouter constructor creates a router without location services. For browser-based routing, you’ll need to add a location plugin (see next step).
3

Add location plugin

For browser-based applications, install a location service plugin:
import { UIRouter } from '@uirouter/core';
import { pushStateLocationPlugin } from '@uirouter/core';

const router = new UIRouter();
router.plugin(pushStateLocationPlugin);
Available location plugins:
  • pushStateLocationPlugin - HTML5 pushState (recommended)
  • hashLocationPlugin - Hash-based routing (#/path)
  • memoryLocationPlugin - In-memory routing (testing)

​
Location Service Plugins

UI-Router Core provides three built-in location service plugins: Uses the HTML5 History API (history.pushState and history.replaceState) for clean URLs: 
import { UIRouter } from '@uirouter/core';
import { pushStateLocationPlugin } from '@uirouter/core';

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

// Clean URLs: /app/dashboard
PushState routing requires server configuration to return index.html for all routes. See your server’s documentation for details.

​
Hash Location

Uses the URL hash (#) for routing, compatible with all browsers and requires no server configuration: 
import { UIRouter } from '@uirouter/core';
import { hashLocationPlugin } from '@uirouter/core';

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

// Hash URLs: #!/app/dashboard

​
Memory Location

Stores location in memory without modifying the browser URL. Useful for testing or non-browser environments: 
import { UIRouter } from '@uirouter/core';
import { memoryLocationPlugin } from '@uirouter/core';

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

// No URL changes, routing state in memory only

​
Services Plugin

For vanilla JavaScript applications, you may also want to include the services plugin, which provides basic dependency injection and promise support: 
import { UIRouter } from '@uirouter/core';
import { servicesPlugin, pushStateLocationPlugin } from '@uirouter/core';

const router = new UIRouter();
router.plugin(servicesPlugin);
router.plugin(pushStateLocationPlugin);
The services plugin provides $q (promise implementation) and $injector (dependency injection) for vanilla JavaScript. Framework-specific implementations typically provide their own services.

​
Advanced: Custom Location Services

You can create a router with custom location services by passing them to the constructor: 
import { UIRouter } from '@uirouter/core';
import { LocationServices, LocationConfig } from '@uirouter/core';

class CustomLocationService implements LocationServices {
  url(newUrl?: string): string {
    // Custom implementation
  }
  
  path(): string {
    // Custom implementation
  }
  
  search(): { [key: string]: any } {
    // Custom implementation
  }
  
  hash(): string {
    // Custom implementation
  }
  
  onChange(callback: Function) {
    // Custom implementation
  }
}

const customLocationService = new CustomLocationService();
const customLocationConfig = new CustomLocationConfig();

const router = new UIRouter(customLocationService, customLocationConfig);

​
Framework-Specific Installation

For framework-specific implementations, use the appropriate package instead: 
npm install @uirouter/angular
Do not install both @uirouter/core and a framework-specific package. The framework packages include the core as a dependency.

​
Verification

Verify your installation by checking the router instance: 
import { UIRouter } from '@uirouter/core';
import { pushStateLocationPlugin } from '@uirouter/core';

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

// Check router services are available
console.log('StateRegistry:', router.stateRegistry);
console.log('StateService:', router.stateService);
console.log('URLService:', router.urlService);
console.log('TransitionService:', router.transitionService);
You should see objects logged for each service, confirming successful installation.

​
Next Steps

Now that you have UI-Router Core installed, continue to the quickstart guide:

Quickstart Guide

Build a complete working router with state registration and navigation

Build docs developers (and LLMs) love

Get started for freeTalk to us