LayoutRouter

The full LayoutRouter API, covering navigation, query parameter helpers, path utilities, and history inspection methods.

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();

// 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

Method	Description
`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

handler: () => void
return: LiveGameEventToken

onPageMount / oncePageMount

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>
  );
}

On this page