Skip to the contentSkip to the navigation
RootsGitHubMenu
Roots 0.4.0the newest docs for this pageAll versions
On this page

roots/router API

Every export of roots/router in Roots 0.4.0, read from runtime/router/index.lisp when this page was built: the declaration, the docstring and the file that defines it. Declarations are TypeScript, printed by the compiler that builds the runtime. A member of a class or of an object has an entry of its own (router.push(), theme.set()). The guides explain how the pieces work together.

Explained in context: the router chapter, Routing, with a live example.

Components #

<RouterLink />
PropTypeDefaultRequired
toanyyes
replaceboolean

Defined in runtime/router/index.lisp.

RouterView #

<RouterView />

Defined in runtime/router/index.lisp.

Functions #

createRouter #

function createRouter(options: RouterOptions): Router

A router; install it with app.use(router).

Defined in runtime/router/index.lisp.

onBeforeRouteLeave #

function onBeforeRouteLeave(guard: NavigationGuard): void

GUARD(to, from) before a navigation leaves this component's route: false cancels, a location redirects, a promise is awaited. Also the place to stop work that belongs to the page.

Defined in runtime/router/index.lisp.

onBeforeRouteUpdate #

function onBeforeRouteUpdate(guard: NavigationGuard): void

GUARD(to, from) before a navigation that keeps this component's route (other params, query or hash).

Defined in runtime/router/index.lisp.

useRoute #

function useRoute(): RouteLocation

The current route: a reactive object (path, fullPath, params, query, hash, name, meta, matched).

Defined in runtime/router/index.lisp.

useRouter #

function useRouter(): Router

The app's router (in setup). R402 when the app has no router.

Defined in runtime/router/index.lisp.

Types #

AfterHook #

type AfterHook = (a: RouteLocation, b: RouteLocation) => unknown;

Defined in runtime/router/index.lisp.

ErrorHook #

type ErrorHook = (a: unknown, b: RouteLocation | null, c: RouteLocation) => unknown;

Defined in runtime/router/index.lisp.

LocationObject #

interface LocationObject {
  path?: string;
  name?: string;
  params?: { [key: string]: unknown };
  query?: { [key: string]: unknown };
  hash?: string;
}

Defined in runtime/router/index.lisp.

type NavigationGuard = (a: RouteLocation, b: RouteLocation) => unknown;

Defined in runtime/router/index.lisp.

type NavigationType = "push" | "replace" | "pop";

Defined in runtime/router/index.lisp.

RouteDefinition #

interface RouteDefinition {
  path: string;
  component?: unknown;
  name?: string;
  props?: unknown;
  meta?: Meta;
  redirect?: unknown;
  alias?: string | string[];
  beforeEnter?: unknown;
  children?: RouteDefinition[];
}

One entry of createRouter({ routes }). PATH: "/users/:id" (static and :param segments) or "*" (not found); the path of a child is relative to its parent ("" is the parent's own path).

Defined in runtime/router/index.lisp.

RouteLocation #

interface RouteLocation {
  readonly path: string;
  readonly fullPath: string;
  readonly params: Params;
  readonly query: Query;
  readonly hash: string;
  readonly name: string | null;
  readonly meta: Meta;
  readonly matched: RouteRecord | null;
  readonly matchedRoutes: RouteRecord[];
  readonly navigationType: NavigationType;
}

A resolved location: what useRoute() and guards see.

Defined in runtime/router/index.lisp.

Router #

class Router {
  readonly records: RouteRecord[];
  readonly history: RouterHistory;
  readonly currentRoute: Ref<RouteLocation>;
  readonly route: RouteLocation;
  resolve(target: RouteTarget): RouteLocation;
  targetString(target: RouteTarget): string;
  href(target: RouteTarget): string;
  push(target: RouteTarget): Promise<boolean>;
  replace(target: RouteTarget): Promise<boolean>;
  go(delta: number): void;
  back(): void;
  forward(): void;
  beforeEach(guard: NavigationGuard): () => void;
  afterEach(hook: AfterHook): () => void;
  afterRender(hook: AfterHook): () => void;
  onError(hook: ErrorHook): () => void;
  isActive(target: RouteTarget, exact: boolean): boolean;
  start(): Promise<boolean>;
  stop(): void;
  isReady(): Promise<boolean>;
  install(app: App): void;
}

router.records #

readonly records: RouteRecord[]

router.history #

readonly history: RouterHistory

router.currentRoute #

readonly currentRoute: Ref<RouteLocation>

router.route #

readonly route: RouteLocation

router.resolve() #

resolve(target: RouteTarget): RouteLocation

The location TARGET (a path, or { path | name, params, query, hash }) points to.

router.targetString() #

targetString(target: RouteTarget): string

router.href() #

href(target: RouteTarget): string

The href for a link to TARGET ("#/path" in hash mode).

router.push() #

push(target: RouteTarget): Promise<boolean>

Navigate to TARGET, adding a history entry. Resolves to true when navigated.

router.replace() #

replace(target: RouteTarget): Promise<boolean>

Navigate to TARGET, replacing the current history entry.

router.go() #

go(delta: number): void

router.back() #

back(): void

router.forward() #

forward(): void

router.beforeEach() #

beforeEach(guard: NavigationGuard): () => void

GUARD(to, from) before every navigation: false cancels, a location redirects, a promise is awaited. Returns a function that removes the guard.

router.afterEach() #

afterEach(hook: AfterHook): () => void

HOOK(to, from) after every completed navigation.

router.afterRender() #

afterRender(hook: AfterHook): () => void

HOOK(to, from) after a navigation has rendered (and the router has scrolled).

router.onError() #

onError(hook: ErrorHook): () => void

HOOK(error, to, from) when a navigation fails: a guard threw, a lazy component did not load. With a hook the errors of back/forward and of the first navigation are the hook's alone; push() and replace() reject either way.

router.isActive() #

isActive(target: RouteTarget, exact: boolean): boolean

router.start() #

start(): Promise<boolean>

Listen to the history (back/forward, URL edits) and run the initial navigation. Done by install; resolves when the initial navigation completes.

router.stop() #

stop(): void

Stop listening to the history (the app was unmounted).

router.isReady() #

isReady(): Promise<boolean>

router.install() #

install(app: App): void

app.use(router): provides the router, registers RouterView/RouterLink, makes <Link to> navigate.

Defined in runtime/router/index.lisp.

RouteRecord #

interface RouteRecord {
  readonly path: string;
  component: unknown;
  readonly name: string | null;
  readonly props: unknown;
  readonly meta: Meta;
  readonly segments: Segment[];
  readonly paramNames: string[];
  readonly score: number[];
  readonly catchAll: boolean;
  readonly parent: RouteRecord | null;
  key: RouteRecord;
  chain: RouteRecord[];
  readonly redirect: unknown;
  readonly beforeEnter: NavigationGuard[];
  readonly loader: (() => unknown) | null;
  loading: unknown;
  readonly matchable: boolean;
}

A compiled route. PATH is the full path (a child's includes its parent's). COMPONENT is null until a lazy component has loaded. KEY is the record itself, or for an alias the record it is an alias of: the redirect, the guards, the loader and the loaded component are read from the key, and RouterView keeps a page mounted while its key stays. CHAIN: the records from the outermost parent to this one.

Defined in runtime/router/index.lisp.

RouterOptions #

interface RouterOptions {
  routes: RouteDefinition[];
  history?: "hash" | "history" | "memory";
  base?: string;
  initial?: string;
  scrollBehavior?: ScrollBehaviorFunction;
  focus?: unknown;
}

Defined in runtime/router/index.lisp.

RouteTarget #

type RouteTarget = string | LocationObject;

Defined in runtime/router/index.lisp.

ScrollBehaviorFunction #

type ScrollBehaviorFunction = (a: RouteLocation, b: RouteLocation, c: ScrollPosition | null) => unknown;

Defined in runtime/router/index.lisp.

ScrollPosition #

interface ScrollPosition {
  left?: number;
  top?: number;
  el?: unknown;
  behavior?: "auto" | "instant" | "smooth";
}

Where to scroll: { left, top } in the document, or { el } (a selector, "#id" or an element; then left and top are an offset kept free above and beside it).

Defined in runtime/router/index.lisp.