Skip to main content
The PageHeader component and its sub-components are used to add action links to the header area of app pages. These components allow you to create primary and secondary actions that users can take within your app.
Screenshot of the app page header featuring action buttons
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="/support">Support</PageHeader.PageLink>
    <PageHeader.Link href="https://example.com">External Link</PageHeader.Link>
  </PageHeader.SecondaryActions>
</PageHeader>
To use these components, you’ll need to be on version 0.13.0 or later of the ui-extensions NPM package. You can check your current version by running npm list or npm list -g, and install the latest version by running npm i @hubspot/ui-extensions.
The PageHeader component is the main wrapper component for primary and secondary header actions. It’s recommended to only include one instance of PageHeader in your app, and to avoid adding/removing it dynamically which can result in unexpected behavior. Only PageHeader.PrimaryAction and PageHeader.SecondaryActions are supported as children. 
import { PageHeader } from "@hubspot/ui-extensions/pages";

<PageHeader>
  <PageHeader.PrimaryAction>
    <PageHeader.PageLink to="/">Home</PageHeader.PageLink>
  </PageHeader.PrimaryAction>
</PageHeader>

​
Props

​
PageHeader.PrimaryAction

The PageHeader.PrimaryAction component is a wrapper for the primary action in the page header. It can contain a PageHeader.PageLink component (for navigating to another page in your app) or a PageHeader.Link component (for URLs outside your app pages). The primary action is displayed as a button. PageHeader can contain only one instance of PageHeader.PrimaryAction.
Screenshot of a primary header action button
import { PageHeader } from '@hubspot/ui-extensions/pages';

// Primary action linking to another app page
<PageHeader.PrimaryAction>
  <PageHeader.PageLink to="/docs">Documentation</PageHeader.PageLink>
</PageHeader.PrimaryAction>

// Primary action as external URL
<PageHeader.PrimaryAction>
  <PageHeader.Link href="https://www.hubspot.com">View Details</PageHeader.Link>
</PageHeader.PrimaryAction>
PageHeader.PrimaryAction can only contain PageHeader.PageLink or PageHeader.Link components. No other component types are supported.

​
Props

​
PageHeader.SecondaryActions

The PageHeader.SecondaryActions component is a wrapper for secondary actions that appear in an Actions dropdown menu next to the primary action. It can contain multiple PageHeader.PageLink components (for navigating to other pages in your app) or PageHeader.Link components (for URLs outside your app pages).
Screenshot of several secondary action buttons

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

hubspot.extend<"pages">(() => {
  return <AdvancedHeaderActions />;
});

function AdvancedHeaderActions() {
  return (
    <PageHeader>
      <PageHeader.PrimaryAction>
        <PageHeader.PageLink to="/home">Home</PageHeader.PageLink>
      </PageHeader.PrimaryAction>
      <PageHeader.SecondaryActions>
        <PageHeader.PageLink to="/docs">Documentation</PageHeader.PageLink>
        <PageHeader.PageLink to="/support">Support</PageHeader.PageLink>
        <PageHeader.Link href="https://example.com">External Resource</PageHeader.Link>
      </PageHeader.SecondaryActions>
    </PageHeader>
  );
}

​
Props

The PageHeader.PageLink component renders a button that navigates to another page within your app when clicked. Use this component inside PageHeader.PrimaryAction or PageHeader.SecondaryActions for in-app navigation. 
import { PageHeader } from "@hubspot/ui-extensions/pages";

// Navigate to a static path
<PageHeader.PageLink to="/docs">Documentation</PageHeader.PageLink>

// Navigate with path parameters
<PageHeader.PageLink to="/view-contact/:contactId" params={{ contactId: "123" }}>
  View Contact
</PageHeader.PageLink>

// Navigate with query string parameters
<PageHeader.PageLink to="/search" params={{ query: "hubspot", page: "1" }}>
  Search
</PageHeader.PageLink>

​
Props

The PageHeader.Link component renders a button that opens a URL outside your app when clicked. It behaves like the standard Link component, but is rendered as a button when used inside PageHeader.PrimaryAction or PageHeader.SecondaryActions. 
import { PageHeader } from "@hubspot/ui-extensions/pages";

<PageHeader.Link href="https://www.hubspot.com">Visit HubSpot</PageHeader.Link>

​
Props

​
Guidelines

  • DO: use PageHeader.PrimaryAction for the most important action on the page.
  • DO: use PageHeader.PageLink for navigating to pages within your app and PageHeader.Link for any URLs outside your app pages.
  • DO: keep link labels short and action-oriented (e.g., “Documentation”, “Support”).
  • DO: use PageHeader.SecondaryActions for additional or less common actions.
  • DON’T: include more than one PageHeader.PrimaryAction in a PageHeader.
  • DON’T: include components other than PageHeader.PageLink or PageHeader.Link in PageHeader.PrimaryAction or PageHeader.SecondaryActions.
Last modified on April 14, 2026