Documentation Index
Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
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} />);
// 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 }) => {
...
};
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. |
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. |
import {
useExtensionApi,
// OR
useExtensionContext,
useExtensionActions
} 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";
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:
For documentation on the UI components included in the SDK, check out the UI components reference documentation.
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.infologger.debuglogger.warnlogger.error
Each method accepts a single string argument. Learn more about creating custom log messages for debugging.