Create UI extensions with React (BETA)
Sales Hub
- Enterprise
Service Hub
- Enterprise
After creating a project and a private app within it, you can create a UI extension to customize your HubSpot CRM UI. In this guide, you'll learn how UI extensions work and how to build and customize them.
You can also follow the quickstart guide to build and deploy an example UI extension to your account. Or, check out HubSpot's other sample projects.
- This guide assumes that you're familiar with the general steps to set up your local environment with the CLI and configure a development sandbox, if needed. If you haven't done so, check out the projects setup guide before proceeding.
- Before getting started, check out the UI extensions overview for general information, best practices, and limitations.
- You should also ensure you've updated to the latest version of the CLI by running
npm install -g @hubspot/cli@next
. - This guide assumes that you've already created a project and a private app within it.
Below, learn more about each file along with example code. You can also follow the quickstart guide to create these files from an example project, or view HubSpot's other sample projects.
Within the /src/app
directory, create an /extensions
directory with the following files:
example-card.json
: the custom card configuration.Example.jsx
: the React file that serves as the front end. You can learn more about how to customize your UI extension front end in the UI extension SDK reference below.package.json:
metadata about the extension's front end. This file is required and can be used to include dependencies for your React front end.
In the extensions
directory, you'll also need to install the HubSpot UI extensions npm package by running npm i
@hubspot/ui-extensions
.
type string
The type of extension. Must be |
data object
Custom card metadata, including:
|
objectTypes array
Defines which types of CRM object records the extension will appear on. This will also enable you to pull data from those records when using the |
You can create extensions for both standard object and custom object records. In the card's JSON configuration file, you'll define this within the objectTypes
array.
When building an extension for custom objects, you'll reference the object as p_objectName
(case sensitive). To get this value, make a GET
request to the custom object schema API, then look for the fullyQualifiedName
in the response. Take the fullyQualifiedName
, then remove the HubID number, and use the resulting value for the configuration file.
For example, for a custom object with the fullyQualifiedName
of p123456_Cats
, the correct value to use for the configuration file would be p_Cats
.
With your project files created locally, you can now use hs project dev
to upload the files to HubSpot and start a local development server to view the custom card. Changes you make to your extension files, along with changes to any serverless function files, will
- After running
hs project dev
, select the account you want to work in:
- To create your extension in an existing sandbox, use the arrow keys to select the sandbox, then press Enter.
- To create and test your extension in a new development sandbox, select < Test on a new development sandbox >. Then, name the sandbox and press Enter. HubSpot will then create the new development sandbox in the production account. This sandbox will sync with the production account's data, including CRM object definitions and up to 100 of the most recently created contacts and their associated deals, tickets, and companies (up to 100 each).
- To create and test your extension in the production account, select
< ! Test on this production account ! >
.
The personal access key you provided doesn't include sandbox permissions
, you'll need to deactivate the account's Personal Access Key, then create a new one with sandbox permissions. To do so, run hs auth
, then follow the prompts to select your account. Then, click Deactivate next to the personal access key, and generate a new one with the proper scopes.
Once the project is created, built, and deployed in the selected account, the local development server will start and you can begin building and modifying your extension.
- The browser will automatically refresh to pick up the latest saved front end code (updates made to the React files).
- Changes made to configuration files, such as
app.json
andhsproject.json
, require a manual upload before you can continue development. To upload those changes, first stop the local development server withq
, then runhs project upload
. After your changes are uploaded, runhs project dev
again to restart the server.
With the local development server running, you can view the extension from a contact record in HubSpot (as configured by objectTypes
in the example-card.json
file):
- Log in to your HubSpot account.
- In your HubSpot account, navigate to Contacts > Contacts. Then, click the name of a contact to view its record.
- Click the Custom tab at the top of the contact record.
UI extensions, like any React front-end, are written as React components. However, unlike usual react components, you must register them with HubSpot by including hubspot.extend()
inside the component file instead of exporting them. This is not required when you create a sub-component. For better code, reuse and include them inside your extension.
The hubspot.extend()
function receives the following arguments:
context
: the context object that includes information about the account and user.runServerlessFunction
: the serverless functions to run in the component.actions
: the actions to include in the component.
If you followed the steps above to create your UI extension from scratch, you'll have already copied the code below into your React front end Example.jsx
file.
View the full API for the runServerlessFunction
call below. Note that propertiesToSend
in the call is another way to fetch CRM properties on the serverless function side, rather than using fetchCromObjectProperties
on the React client side. Making this call on the server side will fetch property data when the serverless function is called, versus only when the extension loads. Learn more about fetching CRM data.
Use the addAlert
method to send alert banners as a feedback for any actions to indicate success or failure. addAlert
is a part of the actions
object that can be passed to extension via hubspot.extend
.
Use the addAlert
method to send alert banners as a feedback for any actions to indicate success or failure. addAlert
is a part of the actions
object that can be passed to extension via hubspot.extend
.
The AddAlert
method accepts the following props:
message
: The alert text.type
: the alert color variant. Can be one of:info
: a blue alert to provide general information.success
: a green alert indicating a positive outcome.warning
: a yellow alert indicating caution.danger
: a red alert indicating a negative outcome.tip
: a white alert to provide guidance.
In line 21 above, the alertMessage
value can be passed by the serverless function by including it in sendResponse
.
There are two ways to fetch CRM property data:
fetchCrmObjectProperties
, which can be included in your React files to fetch property data client side at extension load time.propertiesToSend
, which can be included in your serverless functions to fetch property data on the back end at function invocation time.
fetchCrmObejctProperties
Using the fetchCrmObjectProperties
method, you can get property values from the currently displaying CRM record without having to use HubSpot's APIs. This method is a part of the actions
object that can be passed to the extension via hubspot.extend
. You'll first need to add the object to objectTypes
inside the card's .json
config file. The objects you specify in objectTypes
will also set which CRM objects will display the extension.
The response for fetchCrmObjectProperties
is formatted as:
Similar to addAlert
and fetchCrmObjectProperties
, you can pass openIframeModal
to the extension through the actions
object.
The context
object, which is passed to the extension component via hubspot.extend
, contains information related to the authenticated user and HubSpot account. The following is an example of the information you can retrieve via context
.
Thank you for your feedback, it means a lot to us.