> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: f85b0508-5b20-4b54-bb48-ce6402c0247a
---

# App pages reference

> Reference information for building app pages on the latest version of the developer platform.

export const RequiredIndicator = () => {
  return <span className="required-indicator">
      required
    </span>;
};

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.

```shell theme={null}
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.

```json theme={null}
{
  "uid": "my-app-pages",
  "type": "page",
  "config": {
    "entrypoint": "/app/pages/Pages.tsx"
  }
}
```

| Field                             | Type   | Description                                                                                                      |
| --------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `uid` <RequiredIndicator />       | String | The pages component's unique identifier. This can be any string, but should meaningfully identify the component. |
| `type`<RequiredIndicator />       | String | The type of component, which should be `page` in this case.                                                      |
| `config`                          | Object | An object containing configuration details.                                                                      |
| `entrypoint`<RequiredIndicator /> | String | The 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](#app-pages-configuration) (`*-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](/apps/developer-platform/add-features/ui-extensions/extension-points/app-pages/create-app-pages) guide.

## App page URLs

Your app pages can be accessed using the following URL patterns:

| Target                 | URL                                                                             |
| ---------------------- | ------------------------------------------------------------------------------- |
| Home page              | `https://app.hubspot.com/app/{hubId}/{appId}`                                   |
| Home page with params  | `https://app.hubspot.com/app/{hubId}/{appId}?param1Name=param1Value`            |
| Named page             | `https://app.hubspot.com/app/{hubId}/{appId}/{pagePath}`                        |
| Named page with params | `https://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):

```tsx theme={null}
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:

| Property  | Type   | Description                                                                                                                       |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `path`    | String | The current normalized page path (e.g., `"/"`, `"/docs"`).                                                                        |
| `routeId` | String | The `id` of the matched route, as defined on the route's `id` prop. Useful for identifying the active route in layout components. |
| `params`  | Object | An 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:

```tsx theme={null}
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:

| Property                   | Type   | Description                                                                                                                                 |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` <RequiredIndicator /> | String | The path to navigate to (e.g., `"/"` for home, `"/docs"` for a named page). The path will be normalized (e.g., `"docs"` becomes `"/docs"`). |
| `params`                   | Object | An 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:

```tsx theme={null}
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

| Parameter                      | Type        | Description                                                 |
| ------------------------------ | ----------- | ----------------------------------------------------------- |
| `routes` <RequiredIndicator /> | `ReactNode` | A `<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`](#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](/apps/developer-platform/add-features/ui-extensions/extension-points/app-pages/page-routing#route-ids) section in the routing guide for details.

For detailed documentation on routing components including nested routes, path parameters, and wildcard routes, see:

* [Page routing guide](/apps/developer-platform/add-features/ui-extensions/extension-points/app-pages/page-routing)
* [PageRoutes component reference](/apps/developer-platform/add-features/ui-extensions/ui-components/app-page-components/page-routes)

## 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.

```json theme={null}
{
  "name": "hubspot-example-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}
```

## Related resources

* [Create app pages](/apps/developer-platform/add-features/ui-extensions/extension-points/app-pages/create-app-pages)
* [Page routing](/apps/developer-platform/add-features/ui-extensions/extension-points/app-pages/page-routing)
* [Page linking and navigation](/apps/developer-platform/add-features/ui-extensions/extension-points/app-pages/page-linking)
* [Testing app pages](/apps/developer-platform/add-features/ui-extensions/extension-points/app-pages/testing)
* [PageHeader component reference](/apps/developer-platform/add-features/ui-extensions/ui-components/app-page-components/page-header)
* [PageRoutes component reference](/apps/developer-platform/add-features/ui-extensions/ui-components/app-page-components/page-routes)