Skip to main content
Below, find reference information for building app pages.

​
Project structure

To add app pages to an app, create a pages directory within src/app. The pages directory should contain:
  • A JSON configuration file that defines the pages configuration (Pages-hsmeta.json is recommended).
  • A React file that renders the pages component (Pages.jsx or Pages.tsx is recommended).
  • A package.json file to handle any needed dependencies.
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── pages/
            ├── pages-hsmeta.json
            ├── Pages.tsx
            └── package.json

​
App pages configuration

In the *-hsmeta.json configuration file for your app pages, include the properties below. 
{
  "uid": "my-app-pages",
  "type": "pages",
  "config": {
    "entrypoint": "/app/pages/Pages.tsx"
  }
}
FieldTypeDescription
uid StringThe pages component’s unique identifier. This can be any string, but should meaningfully identify the component.
typeStringThe type of component, which should be pages in this case.
configObjectAn object containing configuration details.
entrypointStringThe file path of the pages component’s front-end React code.

​
Building the React front-end

The UI of app pages is created by a React component file, either .jsx or .tsx. This file lives in the pages/ directory alongside the pages configuration JSON file (*-hsmeta.json). In the configuration file, you’ll specify the path of the React file in the entrypoint field. Routes are defined using createPageRouter, which accepts JSX route definitions and returns a React component. For complete examples, see the create app pages guide.

​
App page URLs

Your app pages can be accessed using the following URL patterns:
TargetURL
Home pagehttps://app.hubspot.com/app/{hubId}/{appId}
Home page with paramshttps://app.hubspot.com/app/{hubId}/{appId}?param1Name=param1Value
Named pagehttps://app.hubspot.com/app/{hubId}/{appId}/{pagePath}
Named page with paramshttps://app.hubspot.com/app/{hubId}/{appId}/{pagePath}?param1Name=param1Value
For example, following the URL path structure above, if a user who installed your app has a HubSpot account ID (i.e., their hubId) of 12345 and your app ID was 67890, they could navigate to their home page at the following URL: 
https://app.hubspot.com/app/12345/67890

​
React page hooks

App pages provide hooks to access routing information within your page components.

​
usePageRoute

Use the usePageRoute hook to access the current page path and all parameters (both path parameters and query parameters): 
import { usePageRoute } from "@hubspot/ui-extensions/pages";

const MyPage = () => {
  const { path, routeId, params } = usePageRoute();
  // path will be "/" for the home page or the current page path like "/docs"
  // routeId is the id assigned to the matched route (e.g., "home", "docs")
  // params contains both path parameters and query parameters

  return (
    <>
      <Text>Current path: {path}</Text>
      <Text>Route: {routeId}</Text>
      <Text>Params: {params.foo}, {params.anotherParam}</Text>
    </>
  );
};
The usePageRoute hook returns an object with:
PropertyTypeDescription
pathStringThe current normalized page path (e.g., "/", "/docs").
routeIdStringThe id of the matched route, as defined on the route’s id prop. Useful for identifying the active route in layout components.
paramsObjectAn object containing all parameters, including both path parameters (e.g., :contactId) and query parameters from the URL.

​
Programmatic navigation

You can navigate to app pages programmatically using the navigateToPage action from the useExtensionActions hook: 
import { Button, hubspot, useExtensionActions } from "@hubspot/ui-extensions";

const MyComponent = () => {
  const { navigateToPage } = useExtensionActions();

  const handleNavigate = () => {
    navigateToPage({
      to: '/docs',
      params: { foo: 'bar', anotherParam: 'abc' }
    });
  };

  return (
    <Button onClick={handleNavigate}>
      Go to Documentation
    </Button>
  );
};
The navigateToPage function accepts an options object with the following properties:
PropertyTypeDescription
to StringThe path to navigate to (e.g., "/" for home, "/docs" for a named page). The path will be normalized (e.g., "docs" becomes "/docs").
paramsObjectAn object containing query parameters to include in the URL (e.g., { foo: 'bar' }).

​
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={AppHomePage} />
    <PageRoutes.Route path="/docs" component={AppDocsPage} />
    <PageRoutes.AnyRoute component={AppNotFoundPage} />
  </PageRoutes>
);

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

​
Parameters

ParameterTypeDescription
routes ReactNodeA <PageRoutes> JSX tree defining all routes for your app.

​
Returns

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

​
Page routing components

The PageRoutes component and its sub-components are used with createPageRouter to define routing for app pages:
  • PageRoutes: Container for route definitions. Supports layoutComponent for wrapping child routes with shared UI.
  • PageRoutes.IndexRoute: Defines the home page (index route) that renders at the root URL of your app.
  • PageRoutes.Route: Defines a named page route with a path and component.
  • PageRoutes.AnyRoute: Defines a catch-all route for unmatched paths, useful for custom 404 pages.
Each route sub-component also accepts an optional id prop. When a route matches, the id value is available as routeId from usePageRoute(). See the route IDs section in the routing guide for details. For detailed documentation on routing components including nested routes, path parameters, and wildcard routes, see:

​
Manage dependencies

You can include dependencies for your app pages in a package.json file within the pages/ directory. By default, when adding app pages through the hs project add command, a package.json file will be created for you with the following dependencies:
  • @hubspot/ui-extensions
  • react
  • typescript
To install dependencies for project components with a package.json file, you can run the hs project install-deps command in your project directory. 
{
  "name": "hubspot-example-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}
Last modified on April 14, 2026