UI extensions SDK (BETA)
Sales Hub
- Enterprise
Service Hub
- Enterprise
The UI extensions SDK is the foundation for building UI extensions in HubSpot, containing an assortment of methods, functionalities, tools, and UI components to customize your extensions.
Below, learn about what's offered in the SDK along with usage examples and boilerplate code.
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.
status
returned by runServerlessFunction
is automatically determined by HubSpot and cannot be set manually using sendResponse()
. If the serverless function runs successfully, it will automatically return a status
of SUCCESS
. To trigger an error status, you'll need to build it into your serverless function.
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
. If you want to render an alert within a card, check out the Alert
component.
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:
title
: the bolded title text of the alert.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 three 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.- Use GraphQL to query CRM data through the
/collector/graphql
endpoint. Learn more about querying CRM data using GraphQL. To see an example of using GraphQL to fetch data, check out HubSpot's contact duplicator sample project.
Please note: to make GraphQL requests, your app must include the following scopes:
collector.graphql_schema.read
collector.graphql_query.execute
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.
You can specify individual properties or fetch all properties with an asterisk:
The response for fetchCrmObjectProperties
is formatted as:
Use refreshObjectProperties
to refresh the property data on the CRM record, and any CRM data components on the record without needing to refresh the page. This includes cards added to the record through HubSpot's UI. This method will work for the CRM objects that you include in the extension's .json
file in the objectTypes
array.
Please note: this method will not refresh property values in app cards that are fetched using HubSpot's APIs. Only HubSpot's built-in property fields and properties in CRM data components will be refreshed.
Use the onCrmPropertiesUpdate
to subscribe to changes made to properties on the CRM record and run functions based on those changes. This action is intended to be used like a react hook.
The full API for this method is as follows:
As an example, the following function subscribes to updates made to the contact's first and last name properties, then logs those properties to the console.
You can subscribe to all properties by using an asterisk.
You can handle potential errors by passing the error argument to the callback.
Please note: as of June 24, 2024, the method for including Panel
components has changed. Moving forward:
- Panels are nested within the components that open them.
- Opening the panel is automatically handled by the parent component, rather than requiring reactions.
Extensions using the old method will continue to function, but it's recommended to review the new functionality below and update your extensions as needed.
To add another layer of UI to your extension, you can include overlays using the Modal and Panel components. The Panel
component adds a sidebar overlay, while the Modal
component adds a pop-up box overlay. Whichever type of overlay you want to use, you'll incorporate it in the same way. To see an example of using overlays, check out HubSpot's Overlay example project.
When choosing which type of overlay to use, keep in mind the following:
- Modal: better suited for short messages and action confirmations. A
'danger'
variant is included for destructive actions, such as deleting a contact. - Panel: better suited for longer, compartmentalized tasks that users might need to perform, such as multi-step forms. Includes a
'modal'
variant to obscure page content outside of the panel to focus the user on the panel task.
To add either type of overlay to your extension:
- Add the
overlay
prop to a Button, Link, Tag, or Image component. - Add the
Modal
orPanel
component into theoverlay
prop.
By default, both types of overlay come with a close button in the top right.
To add a secondary closing mechanism, you can include a Button
, Link
, Tag
, or Image
component within overlay
that triggers the closeOverlay
action in an onClick
event. To use this action, you'll need to include the actions argument in hubspot.extend()
.
Please note:
- Only one
Modal
can be open at a time per extension. Opening aModal
when another one is already opened will cause the first one to close. - A
Modal
can be opened from aPanel
, but aPanel
can't be opened from aModal
.
Below are examples of a panel overlay and a modal overlay.
Similar to addAlert
and fetchCrmObjectProperties
, you can pass openIframeModal
to the extension through the actions
object. This action includes a callback, which you can use to run a function when the iframe modal is closed. The callback doesn't receive any parameters.
Learn more by checking out HubSpot's Display an iframe modal sample project.
openIframeModal
takes the following payload:
For example, the following code would result in an extension that opens an iframe on button click. The iframe is configured to contain the Wikipedia homepage with a height and width of 1000px and no padding. Upon closing the modal, a message will be logged to the console.
While there is no component for uploading files, there are a few ways you can upload files:
- Create a custom file type property, then use a CRM property list component to display and manage the property from CRM records. You can upload up to 10 files per file property, and file uploaded via file properties have the same size and type limitations as files uploaded to the file manager.
- Include an iframe modal in the extension that loads an upload page, then upload files through the iframe.
The context
object, which is passed to the extension component via hubspot.extend
, contains information related to the authenticated user and HubSpot account, along with information about where the extension is loading. The following is an example of the information you can retrieve via context
.
Using logger
methods, you can send custom log messages to HubSpot for more in-depth troubleshooting of deployed extensions. Custom log messages will appear in the app's logs in HubSpot, searchable by trace ID. Check out HubSpot's custom logger sample project to see an implementation example.
The following methods are available:
logger.info
logger.debug
logger.warn
logger.error
Each method accepts a single string argument.
For example, the following extension code includes few different log messages to help better identify where an error has occurred:
When an extension fails to load on a CRM record, an error message will display. This error message will contain a trace ID, which you can copy.
Using that trace ID, you can then locate the custom log messages within the app's logs.
- Custom log messages are not sent while in local development mode. They are logged to the browser console instead.
- All logs are sent as batches with a maximum of 100 logs per batch.
- Each HubSpot account is rate limited to 1,000 logs per minute. After exceeding that limit, all logging is stopped until the page is reloaded.
- The logger will queue a maximum of 10,000 pending messages. Any subsequent logs will be dropped until the queue is below the maximum.
- Queued logs are processed at a rate of five seconds per log batch.
- Queued logs are dropped when the page or is refreshed or closed.
Thank you for your feedback, it means a lot to us.