PageOutlet renders the matched child route in a frame. Each new page gets focus, without scrolling, so assistive technology starts reading at it, and the window scrolls to the top. Back and Forward restore where the page was scrolled instead, retrying while its content loads, until the user scrolls or types. A navigation that changes only the query, such as a filter, keeps the page and its scroll.
The stylesheet gives the frame its full width and a short fade, which reduced motion turns off. It sits in the base cascade layer, so the app’s own styles and Tailwind CSS utilities override it. A layout whose nested routes should share one frame, such as a settings page with tabs, passes its own transitionKey.
Closing dialogs when the route changes
A dialog left open across a navigation covers the new page. DialogNavigationProvider closes the dialogs that are open when a navigation commits, before the new page’s effects run:
The router’s root route renders <DialogNavigationObserver />, and its error element <DialogNavigationObserver isErrorScreen />, so a route error closes them too. Each dialog host calls useDialogNavigationDismissal with a reader for its open session, an object that stays the same while the dialog is open, and a function that closes it. Hosts that share a session close it once, and without a provider the hook does nothing.
Page routes with their metadata
Keep each page’s path, title, and description in one route map, and let createPageRouteObject build the router’s routes from it. Each page component receives exactly { title, description } as its props, and usePageRouteMetadata reads the deepest matched page’s, such as for the document’s title:
An eager page becomes { path, handle, element }, and a lazy one { path, handle, HydrateFallback, lazy }, whose lazy resolves to the element. The wrapElement option wraps every page’s element, such as in an error boundary, and HydrateFallback shows while a lazy page loads during hydration. usePageRouteMetadata skips a handle without a string title and description, and gives null when no matched route is a page.
Generated from TSDoc
API reference
Every export of [email protected], 21 in all, with its signature, its errors, and an example.
Turns a dynamic import of a module whose default export is a page component into a page route's lazy function, so the page's code loads only when its route is visited.
Turns a page route's definition into a React Router route object: the page's element, with its title and description as its props, under a handle that usePageRouteMetadata reads. An eager route renders its component; a lazy one loads it when visited, with HydrateFallback shown while it loads during hydration. wrapElement wraps the element either way.
Reports each committed navigation to the surrounding DialogNavigationProvider, in a layout effect, so open dialogs close before the new page's effects open its own. Render it once in the router's root route, and with isErrorScreen in its error element, so a route error closes the dialogs too. Outside a provider, it renders nothing and needs no router.
Closes the dialogs that are open when a navigation commits, without touching history: each dialog host registers with useDialogNavigationDismissal, and a DialogNavigationObserver inside the router reports each committed location. It reads every open session before closing any, so a dialog that closes or replaces another can't make the provider skip or close the wrong one, and hosts that share a session close it once. Without a provider, the hook and the observer do nothing.
Renders the matched child route in a frame that orients each new page: it focuses the frame, without scrolling, and scrolls the window to the top. Back and Forward restore the position the page had instead, retrying while its content loads and grows, until the user scrolls, touches, clicks, or types. A navigation that changes only the query keeps the page and its scroll. While an outlet is mounted, history.scrollRestoration is manual. Import jg-react-router/styles.css for the frame's layout and its fade, which reduced motion turns off.
Signature
PageOutlet(props: IPageOutletProps): ReactElement
Parameters
propsIPageOutletProps
The frame's extra classes, and the key that identifies the page.
Closes a dialog when a navigation commits while its session is open, through the surrounding DialogNavigationProvider. It always calls the latest getSession and onDismiss the component committed, so they needn't be stable, and it closes the session only if getSession still returns the one that was open when the navigation committed. Outside a provider, it does nothing.
Gives the title and description of the deepest matched page route, such as for the document's title or a page header in a layout. A handle without a string title and description is skipped.
Signature
usePageRouteMetadata(): IPageRouteMetadata | null
Returns
IPageRouteMetadata | null
The page's metadata, or null when no matched route is a page route.
classes added to the frame after jg-page-outlet, such as the app's layout classes
transitionKeyproperty
string
what identifies the page: a new value remounts the frame, focuses it, and scrolls to the top. Defaults to the location's pathname, so a navigation that changes only the query keeps the page. A parent route's own key keeps its frame while its nested routes change
A page route's definition: its path, title, and description, any fields an app adds, such as a navigation label, and either its component or a function that loads it.