Skip to main content
The PageRoutes component and its sub-components are used to define routing for app pages. Use createPageRouter to wrap your route definitions, which returns a React component that handles routing. 
import { createPageRouter, PageRoutes } from "@hubspot/ui-extensions/pages";

const PageRouter = createPageRouter(
  <PageRoutes>
    <PageRoutes.IndexRoute component={AppHomePage} />
    <PageRoutes.Route path="/docs" component={AppDocsPage} />
    <PageRoutes.Route path="/support" component={AppSupportPage} />
    <PageRoutes.AnyRoute component={AppNotFoundPage} />
  </PageRoutes>
);

​
Basic example

Here’s a complete example showing how to create multiple pages in your app with routing: 
import React from "react";
import { Text, Heading, hubspot } from "@hubspot/ui-extensions";
import { createPageRouter, PageHeader, PageRoutes, PageLink, PageBreadcrumbs, PageTitle } from "@hubspot/ui-extensions/pages";

const AppHomePage = () => {
  return (
    <>
      <PageBreadcrumbs>
        <PageBreadcrumbs.Current>Home</PageBreadcrumbs.Current>
      </PageBreadcrumbs>
      <PageTitle>Home</PageTitle>

      <Text>This is the home page of your app.</Text>
      <PageLink to="/docs">View Documentation</PageLink>
    </>
  );
};

const AppDocsPage = () => {
  return (
    <>
      <PageBreadcrumbs>
        <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.Current>Documentation</PageBreadcrumbs.Current>
      </PageBreadcrumbs>
      <PageTitle>Documentation</PageTitle>

      <Text>Welcome to the documentation page!</Text>
      <PageLink to="/">Back to Home</PageLink>
    </>
  );
};

const AppNotFoundPage = () => {
  return (
    <>
      <PageBreadcrumbs>
        <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.Current>Not Found</PageBreadcrumbs.Current>
      </PageBreadcrumbs>
      <PageTitle>Page Not Found</PageTitle>

      <Text>The page you're looking for doesn't exist.</Text>
      <PageLink to="/">Go to Home</PageLink>
    </>
  );
};

const PageRouter = createPageRouter(
  <PageRoutes>
    <PageRoutes.IndexRoute component={AppHomePage} />
    <PageRoutes.Route path="/docs" component={AppDocsPage} />
    <PageRoutes.AnyRoute component={AppNotFoundPage} />
  </PageRoutes>
);

const AppPages = () => {
  return (
    <>
      <PageHeader>
        <PageHeader.PrimaryAction>
          <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
        </PageHeader.PrimaryAction>
        <PageHeader.SecondaryActions>
          <PageBreadcrumbs.PageLink to="/docs">Documentation</PageBreadcrumbs.PageLink>
        </PageHeader.SecondaryActions>
      </PageHeader>

      <PageRouter />
    </>
  );
};

hubspot.extend<"pages">(() => <AppPages />);

​
createPageRouter

The createPageRouter function accepts JSX route definitions and returns a React component that handles routing. Call it at the module level with your <PageRoutes> tree: 
import { createPageRouter, PageRoutes } from "@hubspot/ui-extensions/pages";

const PageRouter = createPageRouter(
  <PageRoutes>
    <PageRoutes.IndexRoute component={HomePage} />
    <PageRoutes.Route path="/about" component={AboutPage} />
  </PageRoutes>
);

function App() {
  return <PageRouter />;
}

​
Parameters

ParameterTypeRequiredDescription
routesReactNodeYesA <PageRoutes> JSX tree defining all routes for your app.

​
Returns

A React component (PageRouter) that you render in your app to activate routing.

​
PageRoutes

The PageRoutes component is the container for route definitions. When used as the root element passed to createPageRouter, it defines the top-level routes. When nested inside another <PageRoutes>, it defines a group of sub-routes under a shared path prefix. 
import { createPageRouter, PageRoutes } from "@hubspot/ui-extensions/pages";

const PageRouter = createPageRouter(
  <PageRoutes layoutComponent={AppLayout}>
    <PageRoutes.IndexRoute component={HomePage} />
    <PageRoutes.Route path="/about" component={AboutPage} />
  </PageRoutes>
);

​
Props

​
PageRoutes.IndexRoute

The PageRoutes.IndexRoute component defines the home page (index route) of your app or a nested section. This is the page that will be rendered when users navigate to the base URL of the enclosing PageRoutes. 
<PageRoutes.IndexRoute component={AppHomePage} />

​
Props

​
PageRoutes.Route

The PageRoutes.Route component defines a named page route in your app. Users can navigate to these routes using the path specified in the path prop. 
<PageRoutes.Route path="/docs" component={DocsPage} />
<PageRoutes.Route path="/settings" component={SettingsPage} />

​
Props

​
PageRoutes.AnyRoute

The PageRoutes.AnyRoute component defines a catch-all route that will be rendered when no other routes match. This is useful for displaying a custom 404 or “page not found” message. 
<PageRoutes.AnyRoute component={NotFoundPage} />

​
Props

​
Guidelines

  • DO: use createPageRouter to define your routes and render the returned component.
  • DO: use PageRoutes.IndexRoute to define your app’s home page.
  • DO: use meaningful path names that describe the page content (e.g., “/docs”, “/settings”, “/support”).
  • DO: include a PageRoutes.AnyRoute to handle unmatched routes gracefully.
  • DO: use layoutComponent to share common UI across groups of routes.
  • DO: assign an id to each route when you need to identify the active route in layout components.
Last modified on April 14, 2026