Skip to main content
Once you’ve defined routes in your app, you’ll need to navigate between them. This guide covers the different methods for linking to pages and passing parameters when navigating. For information on how to access parameters in your page components, see the accessing route information section in the routing guide. There are three primary ways to navigate between pages in your app. The PageLink component is the primary way to create clickable links to other pages within your app. 
import { PageLink } from "@hubspot/ui-extensions/pages";

// Link to home page
<PageLink to="/">Home</PageLink>

// Link to a named page
<PageLink to="/docs">Documentation</PageLink>

// Link with query parameters
<PageLink to="/docs" params={{ section: "getting-started" }}>
  Getting Started
</PageLink>
The PageLink component supports the following props:
  • to (string): The path to navigate to (e.g., "/", "/docs")
  • params (object): Query parameters to include in the URL
For more details on the PageLink component, see the PageLink component reference.
The Link component from @hubspot/ui-extensions should only be used for external URLs. Use PageLink for navigating between pages within your app.

​
Using PageHeader actions

Page header actions support linking to app pages using PageLink components: 
import { Link } from "@hubspot/ui-extensions";
import { PageHeader } from "@hubspot/ui-extensions/pages";

<PageHeader>
  <PageHeader.PrimaryAction>
    <PageHeader.PageLink to="/">Home</PageHeader.PageLink>
  </PageHeader.PrimaryAction>
  <PageHeader.SecondaryActions>
    <PageHeader.PageLink to="/docs">Documentation</PageHeader.PageLink>
    <PageHeader.PageLink to="/analytics" params={{ view: "dashboard" }}>
      Analytics Dashboard
    </PageHeader.PageLink>
    <PageHeader.Link href="https://example.com">External Link</PageHeader.Link>
  </PageHeader.SecondaryActions>
</PageHeader>
PageHeader.PrimaryAction and PageHeader.SecondaryActions can only contain PageHeader.PageLink (for internal pages) or PageHeader.Link (for external URLs) components.
For more details on PageHeader components, see the PageHeader component reference.

​
Programmatic navigation

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

const MyComponent = () => {
  const { navigateToPage } = useExtensionActions();
  
  const handleClick = () => {
    navigateToPage({
      to: '/docs',
      params: { section: 'api' }
    });
  };
  
  return <Button onClick={handleClick}>Go to API Docs</Button>;
};
The navigateToPage function accepts an options object with:
  • to (string, required): The path to navigate to
  • params (object, optional): Query parameters to include

​
Linking with path parameters

When your routes include path parameters (e.g., /view-contact/:contactId), you can pass parameter values through the params object. The routing system will automatically substitute matching parameter names into the URL path.

​
Basic path parameter linking

import { PageLink } from "@hubspot/ui-extensions/pages";

// Route definition: <PageRoutes.Route path="/view-contact/:contactId" component={ContactPage} />

// Link to a specific contact
<PageLink 
  to="/view-contact/:contactId"
  params={{ contactId: "123" }}
>
  View Contact
</PageLink>
Generated URL: https://app.hubspot.com/app/{HubID}/{appId}/view-contact/123 The contactId parameter matches the :contactId path parameter, so it gets substituted into the path.

​
Mixing path and query parameters

When you provide multiple parameters, the routing system intelligently separates them: 
<PageLink 
  to="/view-contact/:contactId"
  params={{ 
    contactId: "123",           // Matches :contactId - goes into path
    tab: "activity"             // No match - goes into query string
  }}
>
  Contact Activity
</PageLink>
Generated URL: https://app.hubspot.com/app/{HubID}/{appId}/view-contact/123?tab=activity

​
Multiple path parameters

You can link to routes with multiple path parameters by including all matching parameters: 
// Route definition: 
// <PageRoutes.Route path="/deals/:dealId/notes/:noteId" component={NotePage} />

<PageLink 
  to="/deals/:dealId/notes/:noteId"
  params={{ 
    dealId: "456",                    // Matches :dealId
    noteId: "789",                    // Matches :noteId
    highlightSection: "comments"      // Goes to query string
  }}
>
  View Note
</PageLink>
Generated URL: https://app.hubspot.com/app/{HubID}/{appId}/deals/456/notes/789?highlightSection=comments

​
How parameter substitution works

The routing system follows these rules when generating URLs:
  1. Matching parameters go into the path: If a parameter name matches a path parameter placeholder (e.g., contactId matches :contactId), it replaces that placeholder in the URL.
  2. Non-matching parameters become query parameters: Any parameters that don’t match path parameter names are added to the query string.
  3. Parameter order doesn’t matter: The system will correctly match parameters regardless of the order they appear in the params object.

​
Programmatic navigation with path parameters

The same substitution rules apply when using navigateToPage: 
const { navigateToPage } = useExtensionActions();

const viewContact = (contactId, initialTab) => {
  navigateToPage({
    to: '/view-contact/:contactId',
    params: { 
      contactId: contactId,    // Goes into path
      tab: initialTab          // Goes into query string
    }
  });
};

// Usage
viewContact("12345", "overview");
// Navigates to: /view-contact/12345?tab=overview
For details on how to access parameters in your page components using usePageRoute, including parameter limitations and best practices, see the Accessing route information section in the routing guide.

​
See also

Last modified on April 14, 2026