API Reference

Core API

createRouter

Create a router instance

const router = createRouter([routes], [options], [dependencies])

• routes: your application routes, see defining routes

• options: your router options, see router options

• dependencies: the dependencies you want to make available in middleware and plugins, see dependency injection

cloneRouter

Clone an existing router.

const clonedRouter = cloneRouter(router, dependencies)

• router: the router instance to clone

• dependencies: the new dependencies, for the cloned router (optional)

add

Add routes, see defining routes

router.add(routes)

start

router.start(startPathOrState, [done])

• startPathOrState: a starting path (string) or state (object). When using browserPlugin, this argument is optional: path will be read from the document location

• done: a done callback (done(err, state))

isStarted

Check if the router is in a started state

router.isStarted()

navigate

Navigate to a new route

router.navigate(routeName, [routeParams], [options], [done])

• routeName: the name of the route to navigate to

• routeParams: the route params

• options: options for the transition (replace, reload, skipTransition, force or any custom option)

• done: a done callback (done(err, state))

navigateToDefault

Navigate to the default route (if any)

router.navigateToDefault([opts], [done])

Stop

Stop your router

router.stop()

cancel

Cancel the current transition (if any)

router.cancel()

forward

Set a route to forward to another route (when navigating to the first one)

router.forward(fromRoute, toRoute)

getState

Return the current state

const state = router.getState()

getOptions

Return current options

router.getOptions()

setOption

Set an option

router.setOption(name, value)

setDependency

Set a dependency

router.setDependency(dependencyName, dependency)

setDependencies

Set dependencies

router.setDependencies(dependencies)

getDependencies

Return the current dependencies

const dependencies = router.getDependencies()

useMiddleware

Register one or multiple middlewares, see middleware

const remove = router.useMiddleware(...middlewares)

clearMiddleware

Remove all middleware

router.clearMiddleware()

usePlugin

Register one or multiple plugins, see plugins

const teardown = router.usePlugin(...plugins)

canActivate

Set a canActivate handler for the provided route name, see preventing navigation

router.canActivate(name, canActivateHandler)

canDeactivate

Set a canDeactivate handler for the provided route name, see preventing navigation

router.canDeactivate(name, canDeactivateHandler)

clearCanDeactivate

Remove a canDeactivate handler for the provided route name

router.clearCanDeactivate(name)

buildPath

Build a path given a route name and params

router.buildPath(route, params)

matchPath

Attempt to match a path

router.matchPath(path, [source])

setRootPath

Set the root path

router.setRootPath(rootPath)

isActive

Check if the provided route is currently active

router.isActive(name, params, [strictEquality], [ignoreQueryParams])

• name: the route name

• params: the route params

• strictEquality: whether to check if the given route is the active route, or a descendant of the active route (false by default)

• ignoreQueryParams: whether to ignore query params (true by default)

areStateEqual

Compare two route state objects

router.areStatesEqual(state1, state2, ignoreQueryParams)

areStatesDescendants

Check if a state is a descendant of another state

router.areStatesDescendants(parentState, childState)

Browser plugin

See in the browser

The browser plugin adds the following to your router instance:

buildUrl

Build an URL

router.buildUrl(routeName, routeParams)

matchUrl

Match an URL

router.matchUrl(url)

replaceHistoryState

Replace state in history and silently update your router instance state. Use if you know what you are doing.

router.replaceHistoryState(name, params)