> ## 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.

---
id: 9283b7bf-d34c-4b9e-b28d-74cbf34f76f0
---

# UI extensions SDK overview

> Learn more about the UI extensions SDK, which provides utilities for app cards.

export const Tag = ({children, type = 'default', className = ''}) => {
  return <span className={`tag tag-${type} ${className}`.trim()}>
      {children}
    </span>;
};

The UI extensions SDK is the foundation for adding [app card](/apps/developer-platform/add-features/ui-extensions/extension-points/app-cards/overview) 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.

```jsx wrap theme={null}
hubspot.extend(({ context, actions }) => <Extension context={context} sendAlert={actions.addAlert} />);
```

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

```jsx theme={null}
// 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.

```jsx theme={null}
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`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#useextensioncontext) hook directly within your component.

For a full list of supported fields, refer to the [context reference documentation](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/context).

## 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`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#useextensionactions) hook directly within your component.

For more detail about using the actions, refer to the [actions reference documentation](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions).

<Info>
  Note that some UI components include a set of actions separate from the SDK actions below, such as the [CRM action components](/apps/developer-platform/add-features/ui-extensions/ui-components/crm-data-components/overview).
</Info>

<Card>
  **Universal actions**

  Supported in all extension points: `settings`, `home`, `crm.record.tab`, `crm.record.sidebar`, `crm.preview`, `helpdesk.sidebar`

  | Action                                                                                                                        | Description                        |
  | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
  | [`addAlert`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#display-alert-banners)             | Display alert banners to the user. |
  | [`reloadPage`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#reload-page)                     | Reload the current page.           |
  | [`copyTextToClipboard`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#copy-text-to-clipboard) | Copy text to the user's clipboard. |
  | [`closeOverlay`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#open-overlays)                 | Close an open overlay or modal.    |
  | [`openIframeModal`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#open-an-iframe-in-a-modal)  | Open an iframe in a modal window.  |
</Card>

<Card>
  **CRM property actions**

  Only available in `crm.record.tab`, `crm.record.sidebar`, `crm.preview`, `helpdesk.sidebar`

  | Action                                                                                                                                   | Description                                        |
  | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
  | [`fetchCrmObjectProperties`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#fetch-crm-property-data)      | Fetch property values from the current CRM record. |
  | [`refreshObjectProperties`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#refresh-crm-record-properties) | Refresh CRM record properties on the page.         |
  | [`onCrmPropertiesUpdate`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#listen-for-property-updates)     | Listen for updates to CRM record properties.       |
</Card>

<Tip>
  While there isn't a dedicated UI component for uploading files, learn about options for [uploading files](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#upload-files) in UI extensions.
</Tip>

## 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](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks).

<Card>
  **Universal hooks**

  Supported in all extension points: `crm.record.tab`, `crm.record.sidebar`, `crm.preview`, `helpdesk.sidebar`, `settings`, `home`

  | Hook                                                                                                                     | Description                                                    |
  | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
  | [`useExtensionApi`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#useextensionapi)         | Access both context and actions from a single hook.            |
  | [`useExtensionContext`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#useextensioncontext) | Access contextual information about the extension environment. |
  | [`useExtensionActions`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#useextensionactions) | Access actions that can be performed within HubSpot.           |
  | [`useCrmSearch`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#usecrmsearch)               | Search CRM records by query or structured filters.             |
  | [`useDebounce`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#usedebounce)                 | Debounce a rapidly-changing value.                             |

  ```jsx wrap theme={null}
  import {
    useExtensionApi,
    useExtensionContext,
    useExtensionActions,
    useCrmSearch,
    useDebounce
  } from "@hubspot/ui-extensions";
  ```
</Card>

<Card>
  **CRM-specific hooks**

  Only available in `crm.record.tab`, `crm.record.sidebar`, `crm.preview`, `helpdesk.sidebar`

  | Hook                                                                                                               | Description                                   |
  | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
  | [`useCrmProperties`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#usecrmproperties) | Fetch properties from the current CRM record. |
  | [`useAssociations`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#useassociations)   | Fetch associated CRM records.                 |

  ```jsx wrap theme={null}
  import {
    useCrmProperties,
    useAssociations
  } from "@hubspot/ui-extensions/crm";
  ```
</Card>

## 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`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#fetch-crm-property-data), or from `hubspot.fetch()` and serverless function requests.

For more detail, refer to the [utilities reference documentation](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/utilities).

## 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](/apps/developer-platform/add-features/ui-extensions/ui-components/overview#standard-components) are imported from `'@hubspot/ui-extensions'`
* [CRM data](/apps/developer-platform/add-features/ui-extensions/ui-components/overview#crm-data-components) and [CRM action components](/apps/developer-platform/add-features/ui-extensions/ui-components/overview#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](/apps/developer-platform/add-features/ui-extensions/ui-components/overview).

## Tools

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

* **[Linting](/apps/developer-platform/add-features/ui-extensions/tools/linting/overview):** 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](/apps/developer-platform/add-features/ui-extensions/tools/testing/overview):** 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](/apps/developer-platform/add-features/ui-extensions/logging-and-monitoring).

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](/apps/developer-platform/add-features/ui-extensions/logging-and-monitoring#custom-log-messages).