Documentation
Player
Page Router
LayoutRouter

LayoutRouter

LayoutRouter manages navigation between pages and nested layouts. It replaces the previous linear PageRouter and works together with Layout and Page components to build a directory-like route tree.

import { useRouter } from "narraleaf-react";
 
const router = useRouter();

Basic navigation

// Absolute navigation
router.navigate("/home");
 
// With query parameters
router.navigate("/user/profile", { tab: "info" });
 
// Relative navigation
router.navigate("./detail");
 
// History control
router.back();
router.forward();
 
// Replace without pushing history
router.replace("/settings");
 
// Clear current page & history
router.clear();
 
// Keep current page but drop history
router.cleanHistory();

Query helpers

router.setQueryParam("lang", "en");
router.getQueryParam("lang"); // "en"
router.removeQueryParam("lang");
 
router.setQueryParams({ tab: "general", theme: "dark" });
router.clearQueryParams();

Path helpers

MethodDescription
resolvePath(path)Resolve a relative path (e.g. ../parent) to an absolute path.
matchPath(path, pattern)Prefix match with * and :param support.
exactMatch(path, pattern)Same as matchPath but requires exact segment count.
extractParams(path, pattern)Extract dynamic parameters from a matched path.

Public Methods

navigate

Navigate to a new path.

  • path: string – target path, absolute or relative
  • queryParams?: Record<string,string> – optional query parameters
  • return: this
router.navigate("/about");

back

Go back to previous history entry (if any).

  • return: this

forward

Go forward to next history entry (if any).

  • return: this

replace

Replace current path without adding a new history entry.

  • path: string – new path
  • queryParams?: Record<string,string> – optional query parameters
  • return: this

clear

Clear current path and history.

  • return: this

cleanHistory

Remove all history records except the current entry.

  • return: this

getCurrentPath / getPathname

Get the current path (without query).

  • return: string

getCurrentQuery / getQueryParams

Get current query parameters object.

  • return: Record<string,string>

getCurrentUrl

Get current full URL (path + query).

  • return: string

setQueryParam

Set a single query parameter.

  • key: string
  • value: string
  • return: this

setQueryParams

Merge multiple query parameters.

  • params: Record<string,string>
  • return: this

getQueryParam

Get a query parameter value.

  • key: string
  • return: string | undefined

removeQueryParam

Remove a query parameter.

  • key: string
  • return: this

clearQueryParams

Remove all query parameters.

  • return: this

hasQueryParam

Check whether a query parameter exists.

  • key: string
  • return: boolean

getQueryParamKeys

Get all query parameter keys.

  • return: string[]

getQueryParamCount

Get number of query parameters.

  • return: number

getHistory

Get full navigation history.

  • return: string[]

getHistoryIndex

Get current index inside history array.

  • return: number

canGoBack / canGoForward

Check if router can go back / forward.

  • return: boolean

parseUrl

Parse a URL string into { path, query }.

  • url: string
  • return: { path:string; query:Record<string,string>; }

buildUrl

Build full URL from path and query object.

  • path: string
  • query: Record<string,string>
  • return: string

resolvePath

Resolve a relative path to absolute path.

  • path: string
  • return: string

normalizePath

Normalize duplicate or trailing slashes in a path.

  • path: string
  • return: string

joinPath

Join multiple path segments and normalize the result.

  • path: string – base path
  • ...paths: string[] – additional segments
  • return: string

parsePath

Split a path into segments.

  • path: string
  • return: string[]

buildPath

Build path string from segments array.

  • segments: string[]
  • return: string

getParentPath

Get parent path of a given path.

  • path: string
  • return: string

matchPath

Prefix path matching supporting * and :param.

  • path: string
  • pattern: string
  • return: boolean

exactMatch

Exact path matching (segment count must match).

  • path: string
  • pattern: string
  • return: boolean

extractParams

Extract route parameters based on pattern.

  • path: string
  • pattern: string
  • return: Record<string,string>

onExitComplete / onceExitComplete

Register handler executed after all exit animations completed.

  • handler: () => void
  • return: LiveGameEventToken

onPageMount / oncePageMount

Register handler executed when a page component mounts.

  • handler: () => void
  • return: LiveGameEventToken

Inspection

router.getCurrentPath();  // "/user/profile"
router.getCurrentQuery(); // { tab: "info" }
router.getCurrentUrl();   // "/user/profile?tab=info"
 
router.getHistory();      // ["/home", "/user/profile"]
router.canGoBack();
router.canGoForward();

Example with Layout & Page

import { RouterProvider, RootLayout, Layout, Page, useRouter } from "narraleaf-react";
 
function MyPages() {
  return (
    <RouterProvider>
      <RootLayout>
        {/* /home */}
        <Layout name="home">
          {/* default page: /home */}
          <Page name={null}>
            <Home />
          </Page>
 
          {/* /home/detail */}
          <Page name="detail">
            <Detail />
          </Page>
        </Layout>
 
        {/* /about */}
        <Layout name="about">
          <Page name={null}>
            <About />
          </Page>
        </Layout>
      </RootLayout>
    </RouterProvider>
  );
}
Page RouterLayout