Last modified: September 3, 2025
App home pages let you create a custom landing experience for users when they navigate to your app in HubSpot. Built with React and powered by the UI extensions SDK, home pages are built with the same toolkit available for app cards and settings pages, including HubSpot’s UI components and data fetching utilities. Below, learn how to create an app home page on the latest version of the developer platform (2025.2).

​
Prerequisites

​
Create an app home page

1

Add an app home component to your project

To add a home page component to an existing app, use the terminal to navigate into your local project directory, then run the following command:
hs project add
Then, when prompted to select a component to add, select Home.Screenshot of the terminal prompt for selecting the type of component to addA new pages/ directory will be created in the project’s src/app/ directory. The pages/ directory will contain:
  • A JSON configuration file (*-hsmeta.json)
  • A React component file (.tsx)
  • A package.json file

myProject
└── src/
    └── app/
        └── pages/
            ├── home-hsmeta.json
            ├── Home.tsx
            └── package.json


{
 "uid": "app-home",
 "type": "page",
 "config": {
   "entrypoint": "/app/pages/Home.tsx",
   "location": "home"
 }
}
2

Upload to HubSpot

To upload your home page to HubSpot:
  • Run hs project install-deps from within your local project directory to install necessary dependencies. This will create a package-lock.json file, which will speed up the project build time and ensure that any dependencies in your local development environment and production match.
  • Then, run hs project upload.
  • After the project finishes deploying, open the project in HubSpot by running hs project open. Alternatively, in HubSpot you can navigate to Development > Projects, then click the name of your project.
  • Your home component should now be listed on the details page.
Screenshot of the home component on project details page

​
View the app home page in HubSpot

To verify the home page is working correctly:
  • In the HubSpot account where you’ve installed the app, click the Marketplace icon, then click Connected apps.
Navigate to connected apps in developer test account
  • Click the My apps tab to view a list of the account’s currently installed apps.
  • Click the name of your app, which will redirect you to your app’s home page.
Screenshot of an app's settings page in HubSpot.
You can now continue to build out your app’s home page as needed. Similar to building app cards, you’ll use the UI extensions SDK to add functionality and visual elements to your home page. Note that all the existing limitations around building UI extensions apply to building a settings page.
  • Use hubspot.fetch to leverage your backend to save and retrieve settings. Learn more about using this approach in the legacy documentation.
  • Check out the reference documentation on standard components for how to use React components when building your extension, or use the component in the Figma Design Kit.
  • Use the hs project dev command to iteratively build out your settings page and preview your changes locally.
The local development server will only pick up changes saved to the front-end React file. If you update the *-hsmeta.json or package.json files, you’ll need to stop the server, upload your changes, then start the server again.

​
Home page components

In addition to the full set of UI components, there are three UI components specific to app home pages that you can use together to add action buttons to the header area:
  • <HeaderActions>
  • <PrimaryHeaderActionButton>
  • <SecondaryHeaderActionButton>
To use these components, you’ll need to be on version 0.10.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.
These components imported from @hubspot/ui-extensions/pages/home.
Screenshot of the app home screen featuring the header action buttons
import {
  HeaderActions,
  PrimaryHeaderActionButton,
  SecondaryHeaderActionButton
  } from '@hubspot/ui-extensions/pages/home';

<HeaderActions>
  <PrimaryHeaderActionButton onClick={() => console.log('P1')}>
    Primary
  </PrimaryHeaderActionButton>
  <SecondaryHeaderActionButton onClick={() => console.log('S1')}>
    Secondary 1
  </SecondaryHeaderActionButton>
  <SecondaryHeaderActionButton onClick={() => console.log('S2')}>
    Secondary 2
  </SecondaryHeaderActionButton>
</HeaderActions>
Below, learn more about each component.

​
HeaderActions

The HeaderActions component is the main wrapper component for the primary and secondary header action button components. It’s recommended to only include one instance of HeaderActions in your app, and to avoid adding/removing it dynamically which can result in unexpected behavior. Only PrimaryHeaderActionButton and SecondaryHeaderActionButton are supported as children. 
import {
  HeaderActions,
  PrimaryHeaderActionButton
} from '@hubspot/ui-extensions/pages/home';

<HeaderActions>
  <PrimaryHeaderActionButton>
    Primary button
  </PrimaryHeaderActionButton>
</HeaderActions>

​
PrimaryHeaderActionButton

The PrimaryHeaderActionButton component renders an orange button, and should be used for the primary action on the home page. HeaderActions can contain only one instance of PrimaryHeaderActionButton. For additional buttons, use SecondaryHeaderActionButton.
Screenshot of a primary header action button
import {
  HeaderActions,
  PrimaryHeaderActionButton
} from '@hubspot/ui-extensions/pages/home';

// Basic primary button
<PrimaryHeaderActionButton href="https://example.com" OnClick={() => saveData()}>
  Save changes
</PrimaryHeaderActionButton>

// Primary button as link
<PrimaryHeaderActionButton
  href={{
    url: 'https://www.hubspot.com',
    external: true
  }}
>
View details
</PrimaryHeaderActionButton>
PropTypeDescription
children (required)ReactNodeThe button text or content.
onClick() => voidA function that will be invoked when the button is clicked. It receives no arguments and it’s return value is ignored.
hrefString | ObjectInclude this prop to open a URL on click. Contains the following fields:
  • url (string): the URL that will open on click.
  • external (boolean): set to true to open the URL in a new tab and display an external link icon. By default:
    • Links to HubSpot app pages will open in the same tab and will not include an icon.
    • Links to non-HubSpot app pages will open in a new tab and include the icon.
When a button includes both href and an onClick action, both will be executed on button click.
disabledBooleanWhen set to true, the button will render in a greyed-out state and cannot be clicked.
overlayObjectInclude a Modal or Panel component in this object to open it as an overlay on click. Learn more about using overlays.

​
SecondaryHeaderActionButton

The SecondaryHeaderActionButton component renders additional buttons that appear in an Actions dropdown menu next to the primary button. You can include multiple secondary buttons, and each will appear as another item in the Actions dropdown menu.
Screenshot of several secondary action buttons
import {
  HeaderActions,
  PrimaryHeaderActionButton,
  SecondaryHeaderActionButton
} from '@hubspot/ui-extensions/pages/home';

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

function AdvancedHeaderActions() {
  const [isSaving, setIsSaving] = useState(false);

  const handleSave = async () => {
    setIsSaving(true);
    try {
      console.log('Saving...');
    } finally {
      setIsSaving(false);
    }
  };

  return (
    <HeaderActions>
      <PrimaryHeaderActionButton
        onClick={handleSave}
        disabled={isSaving}
      >
        {isSaving ? 'Saving...' : 'Save Changes'}
      </PrimaryHeaderActionButton>
      <SecondaryHeaderActionButton onClick={() => console.log('Export Data')}>
        Export Data
      </SecondaryHeaderActionButton>
      <SecondaryHeaderActionButton onClick={() => console.log('Share')}>
        Share
      </SecondaryHeaderActionButton>
      <SecondaryHeaderActionButton href="https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/create-an-app-home-page">
        Help docs
      </SecondaryHeaderActionButton>
    </HeaderActions>
  );
}