UI extensions SDK overview

The UI extensions SDK is the foundation for adding app card functionality, providing methods and utilities that enable you to:

Access account, extension, and user context
Perform actions like displaying alert banners
Access context, perform actions, or fetch data using hooks
Render the UI through UI components
Use tooling for testing, linting, and sharing code
Log custom messages for debugging

Register the extension

UI extensions, like any React front-end, are written as React components. However, unlike typical React components, you must register your UI extension with HubSpot by including hubspot.extend() inside the component file instead of exporting it. This is not required when you create a sub-component. For cleaner code, reuse and include them inside your extension. The hubspot.extend() function receives the following arguments:

context: provides account, extension, and user context to the extension.
actions: makes actions available to the extension.

hubspot.extend(({ context, actions }) => <Extension context={context} sendAlert={actions.addAlert} />);

The provided arguments can then be passed to the extension component as props.

// Define the extension to be run within HubSpot
hubspot.extend(({ context, actions }) => (
  <Extension
    context={context}
    sendAlert={actions.addAlert}
  />
));
// Define the Extension component, taking in context, and sendAlert as props
const Extension = ({ context, sendAlert }) => {
  ...
};

If your extension doesn’t need to access context or perform actions, you don’t need to provide these arguments to hubspot.extend() or the extension component.

hubspot.extend(() => <Extension />);
const Extension = () => {
  ...
};

Context

The context object contains data related to the authenticated user and HubSpot account (e.g., Hub ID, user’s email), along with data about where the extension was loaded (e.g., the UI extension’s location). You can access context data using either approach:

Props-based approach: destructure context from the callback passed to hubspot.extend(), then pass it to your component as a prop.
Hook-based approach: call the useExtensionContext hook directly within your component.

For a full list of supported fields, refer to the context reference documentation.

Actions

Below are the actions you can perform with the SDK. You can access actions using either a props-based approach or a hook-based approach:

Props-based approach: destructure actions from the callback passed to hubspot.extend(), then pass it to your component as a prop.
Hook-based approach: call the useExtensionActions hook directly within your component.

For more detail about using the actions, refer to the actions reference documentation.

Note that some UI components include a set of actions separate from the SDK actions below, such as the CRM action components.

Universal actionsSupported in all extension points: settings, home, crm.record.tab, crm.record.sidebar, crm.preview, helpdesk.sidebar

Action	Description
`addAlert`	Display alert banners to the user.
`reloadPage`	Reload the current page.
`copyTextToClipboard`	Copy text to the user’s clipboard.
`closeOverlay`	Close an open overlay or modal.
`openIframeModal`	Open an iframe in a modal window.

CRM property actionsOnly available in crm.record.tab, crm.record.sidebar, crm.preview, helpdesk.sidebar

Action	Description
`fetchCrmObjectProperties`	Fetch property values from the current CRM record.
`refreshObjectProperties`	Refresh CRM record properties on the page.
`onCrmPropertiesUpdate`	Listen for updates to CRM record properties.

While there isn’t a dedicated UI component for uploading files, learn about options for uploading files in UI extensions.

Hooks

The SDK provides hooks to simplify accessing context, performing actions, and fetching CRM data within UI extensions. These hooks are optimized to prevent unnecessary re-renders and automatically clean up resources when components unmount. You can pass inline arrays and objects to the hooks directly, as memoization is not required. For more detail about using the hooks, refer to the hooks reference documentation.

Universal hooksSupported in all extension points: crm.record.tab, crm.record.sidebar, crm.preview, helpdesk.sidebar, settings, home

Hook	Description
`useExtensionApi`	Access both context and actions from a single hook.
`useExtensionContext`	Access contextual information about the extension environment.
`useExtensionActions`	Access actions that can be performed within HubSpot.
`useCrmSearch`	Search CRM records by query or structured filters.
`useDebounce`	Debounce a rapidly-changing value.

import {
  useExtensionApi,
  useExtensionContext,
  useExtensionActions,
  useCrmSearch,
  useDebounce
} from "@hubspot/ui-extensions";

CRM-specific hooksOnly available in crm.record.tab, crm.record.sidebar, crm.preview, helpdesk.sidebar

Hook	Description
`useCrmProperties`	Fetch properties from the current CRM record.
`useAssociations`	Fetch associated CRM records.

import {
  useCrmProperties,
  useAssociations
} from "@hubspot/ui-extensions/crm";

Utilities

The SDK provides utility functions for working with CRM data outside of hooks and actions. Currently, this includes formatCrmProperties, which applies HubSpot’s display formatting to raw CRM property values you’ve retrieved from an action like fetchCrmObjectProperties, or from hubspot.fetch() and serverless function requests. For more detail, refer to the utilities reference documentation.

UI components

When building a UI extension, you can include HubSpot-provided reusable components, ranging from simple text fields to out-of-the-box CRM object reports. Components are imported at the top of your tsx or jsx extension file from one of two SDK directories:

Standard components are imported from '@hubspot/ui-extensions'
CRM data and CRM action components are imported from '@hubspot/ui-extensions/crm'

For documentation on the UI components included in the SDK, check out the UI components reference documentation.

Tools

Tooling is available to improve the extension development experience and catch issues before deployment.

Linting: platform-specific constraints and best practices enforced by the @hubspot/eslint-config-ui-extensions ESLint plugin. These rules catch issues and give immediate feedback so you can fix problems before deploying an extension. The linting tools catch common platform violations, like using document, fetch, or native HTML elements.
Testing: automated tests to help catch regressions before deploying. The @hubspot/ui-extensions/testing module provides a test renderer that simulates the extension environment, so you can render components, trigger events, and assert on output without deploying.
TypeScript: TypeScript helps catch platform constraint violations while editing, before you run code. For the best experience, configure your tsconfig.json with "lib": ["ES2020", "WebWorker"]. This excludes DOM types from the type checker, so your editor treats document, window, and native fetch as errors, matching the actual runtime environment.

Custom log messages

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. The following methods are available:

logger.info
logger.debug
logger.warn
logger.error

Each method accepts a single string argument. Learn more about creating custom log messages for debugging.

​Register the extension

​Context

​Actions

​Hooks

​Utilities

​UI components

​Tools

​Custom log messages

Register the extension

Context

Actions

Hooks

Utilities

UI components

Tools

Custom log messages