UI extensions overview

​

When to use UI extensions

• You want to display external system data in HubSpot.
• You need to guide users through multi-step flows.
• You want to enable users to customize CRM records with richer functionality than HubSpot’s default UI allows.
• You want HubSpot to host your app’s configuration UI.
• You need a secure and scalable way to embed custom UI logic without hosting your own frontend architecture.

​

How UI extensions work

• A JSON configuration file (*-hsmeta.json) that registers where the extension appears in HubSpot and specifies the entry point.
• An entry point (hubspot.extend()) that initializes the extension and receives context and actions from HubSpot.
• A React component (.jsx or .tsx) that defines your UI. TypeScript is fully supported and recommended for better type safety.
• Optional data fetching via the hubspot.fetch() API to request data from external services.

1. HubSpot loads your extension in a secure, sandboxed environment.
2. Context is passed into your component, including information about the current user, HubSpot account, and (for CRM extensions) the current record’s ID and object type.
3. Your component can fetch CRM data using SDK hooks or call external services using hubspot.fetch().
4. The UI renders and reacts to user interactions.

​

What you can build

​

App cards

• Displaying enriched company or contact data.
• Embedding task lists, timeline details, or customer insights.
• Triggering external workflows or actions from within a record.
• Rendering custom layouts, accordions, tables, and charts.

​

App home pages

• Building analytics dashboards.
• Enabling multi-step flows or guided processes.
• Aggregating cross-object CRM insights.
• Creating custom workspace experiences.

​

Settings pages

• Managing API keys or OAuth credentials.
• Managing feature toggles or custom configuration.
• Connecting external services.
• Mapping CRM properties to external systems.

​

Building UI extensions

1. Create the extension: run the hs project add command to add a card, home page, or settings page component to an existing project. Or, follow the quickstart to build your first extension.
2. Build with React: build your extension’s UI with React or TypeScript, using HubSpot’s UI component library to render elements.
3. Register with the SDK: use hubspot.extend() to register your extension with HubSpot.
4. Upload and test: run hs project upload to deploy, and hs project dev for local development. You can also build testing into your project using a set of provided testing utilities.

​

Supported locations

{
  "uid": "example-card",
  "type": "card",
  "config": {
    "name": "Hello Example App",
    "description": "A description of the card's purpose.",
    "location": "crm.record.tab",
    "entrypoint": "/app/cards/ExampleCard.jsx",
    "objectTypes": ["contacts"]
  }
}

​

The UI extensions SDK

• Context access: retrieve information about the current user, account, and CRM record.
• Actions: display alerts, copy text to clipboard, reload pages, and open overlays.
• CRM data hooks: fetch CRM properties and associations using useCrmProperties and useAssociations. Learn more about logging and monitoring for UI extensions.

​

Fetching external data

• Configuring permitted URLs.
• Request signing and validation.
• Proxying requests during local development.

​

UI components

• Standard components: general-purpose components like buttons, forms, tables, and layout components. Imported from @hubspot/ui-extensions.
• CRM data components: components that automatically fetch and display data from CRM records, such as property lists, association tables, and reports. Imported from @hubspot/ui-extensions/crm.
• CRM action components: components that trigger built-in CRM actions like adding notes, sending emails, or creating records. Imported from @hubspot/ui-extensions/crm.

​

Local development and testing

• Rendering components in a test environment.
• Querying and interacting with rendered output.
• Mocking context, actions, and CRM data hooks.
• Debugging rendered component trees.

​

Code quality and linting

​

Next steps

• Quickstart: create your first app on the developer platform.
• Create an app card: create a custom card that displays on CRM records.
• Create a home page: build a landing page for your app.
• Create a settings page: add a configuration interface for your app.