UI extensions SDK versioning

HubSpot will regularly release new versions of the UI extensions SDK to provide new features, hooks, and components to use in your app. Once a new version is released, the previous version will be supported for 18 months. New versions are generally released every 6 months.

v0

v0 was the original release of the UI extensions SDK. This version will be supported through March 2028.

v1

The latest version of the UI extensions SDK, v1, was released November 2026, and will be supported through April 2028. To install the latest version of the SDK, run the following command in the top-level working directory of your project:

npm install @hubspot/ui-extensions@^1

The sections below outline the changes made to hooks and components in v1, and how to migrate any associated references in your code.

Migrate to updated hooks

The following data hooks have been renamed:

v0 hook	v1 hook	Import path
`useCrmProperties`	`useRecordPropertiesCurrent`	`@hubspot/ui-extensions/crm`
`useAssociations`	`useRecordAssociationsCurrent`	`@hubspot/ui-extensions/crm`
`useCrmSearch`	`useRecordSearch`	`@hubspot/ui-extensions`

To find all affected references in your code, you can run the command below in the top-level working directory of your project:

grep -r "useCrmProperties\|useAssociations\|useCrmSearch" src/

In addition to the rename, formatting options moved from the second options argument into a format key in the main config. See the examples below.

useCrmProperties updated to useRecordPropertiesCurrent

The useCrmProperties hook has been renamed to useRecordPropertiesCurrent.

  import { useCrmProperties } from '@hubspot/ui-extensions/crm';

  const { properties, isLoading, error } = useCrmProperties(
    ['firstname', 'email'],
    {
      propertiesToFormat: 'all',
      formattingOptions: {
        date: { format: 'MM-DD-YYYY', relative: false },
        currency: { addSymbol: true },
      },
    }
  );

  import { useRecordPropertiesCurrent } from '@hubspot/ui-extensions/crm';

  const { properties, isLoading, error } = useRecordPropertiesCurrent({
    properties: ['firstname', 'email'],
    format: {
      propertiesToFormat: 'all',
      date: { format: 'MM-DD-YYYY', relative: false },
      currency: { addSymbol: true },
    },
  });

useAssociations updated to useRecordAssociationsCurrent

The useAssociations hook has been renamed to useRecordAssociationsCurrent, and the pageLength property is now pageSize.

  import { useAssociations } from '@hubspot/ui-extensions/crm';

  const { results, pagination } = useAssociations(
    { toObjectType: '0-1', properties: ['firstname', 'email'], pageLength: 25 },
    { propertiesToFormat: 'all', formattingOptions: { date: { format: 'MM-DD-YYYY' } } }
  );

  import { useRecordAssociationsCurrent } from '@hubspot/ui-extensions/crm';

  const { results, pagination } = useRecordAssociationsCurrent({
    toObjectType: '0-1',
    properties: ['firstname', 'email'],
    pageSize: 25,
    format: {
      propertiesToFormat: 'all',
      date: { format: 'MM-DD-YYYY' },
    },
  });

useCrmSearch updated to useRecordSearch

The useCrmSearch hook has been renamed to useRecordSearch, and the pageLength property is now pageSize.

  import { useCrmSearch } from '@hubspot/ui-extensions';

  const { results, total, pagination } = useCrmSearch(
    {
      objectType: 'contact',
      properties: ['firstname', 'email'],
      filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }] }],
      sorts: [{ propertyName: 'createdate', direction: 'DESCENDING' }],
      pageLength: 20,
    },
    { propertiesToFormat: 'all', formattingOptions: { currency: { addSymbol: true } } }
  );

import { useRecordSearch } from '@hubspot/ui-extensions';

const { results, total, pagination } = useRecordSearch({
  objectType: 'contact',
  properties: ['firstname', 'email'],
  filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }] }],
  sorts: [{ propertyName: 'createdate', direction: 'DESCENDING' }],
  pageSize: 20,
  format: {
    propertiesToFormat: 'all',
    currency: { addSymbol: true },
  },
});

New Stack component

The new Stack component stacks children vertically, with gap, align, and justify props. For horizontal layouts, use Flex.

// For horizontal layouts: use Flex
<Flex direction="row" gap="medium">
  <Button>Save</Button>
  <Button variant="secondary">Cancel</Button>
</Flex>

// For vertical layouts: use new Stack component
<Stack gap="medium">
  <Button>Save</Button>
  <Button variant="secondary">Cancel</Button>
</Stack>

Overlay replaces the reactions pattern

Use the overlay prop to open panels and modals. Remove the reactions second argument from all event handlers.

<Button onClick={(event, reactions) => reactions.openPanel('my-panel')}>
  Open
</Button>
<Panel id="my-panel">...</Panel>

<Button overlay={<Panel id="my-panel">...</Panel>}>
  Open
</Button>

This applies to all reactions methods (openPanel, openModal, etc.). The Reactions, PanelAction, ModalAction, and ReactionsHandler types have also been removed. The options prop is removed from the Dropdown component. Instead, use Dropdown.ButtonItem child components to declare dropdown items.

<Dropdown
  buttonText="Actions"
  options={[
    { label: 'Edit', onClick: handleEdit },
    { label: 'Delete', onClick: handleDelete },
  ]}
/>

<Dropdown buttonText="Actions">
  <Dropdown.ButtonItem onClick={handleEdit}>Edit</Dropdown.ButtonItem>
  <Dropdown.ButtonItem onClick={handleDelete}>Delete</Dropdown.ButtonItem>
</Dropdown>

Additional removed props

Consult the table below on other props that have been removed from certain components compared to v0:

Component	Removed prop / value	Replace with
`NumberInput`	`onInput`	`onChange`
`ProgressBar`	`valueMax`	`maxValue`
`Divider`	`distance`	`size`
`Toggle`	`readonly`	`readOnly`
`Toggle`	`size="default"`	`size="medium"`
`Checkbox`, `RadioButton`	`readonly`	`readOnly`
`Checkbox`, `RadioButton`	`size="default"`	`size="medium"`
`Checkbox`, `RadioButton`	`variant`	`size`
`ToggleGroup`	`option.readonly`	`option.readOnly`
`ToggleGroup`	`size="default"`	`size="medium"`
`ToggleGroup`	`variant`	`size`
`Form`	`preventDefault`	No replacement required (default submission is already prevented)
`BarChart`, `LineChart`	`options.colors`	`options.colorList`

Build apps

Add features

Publish to the HubSpot Marketplace

Skeleton group 5

UI extensions SDK versioning

v0

v1

Migrate to updated hooks

useCrmProperties updated to useRecordPropertiesCurrent

useAssociations updated to useRecordAssociationsCurrent

useCrmSearch updated to useRecordSearch

New Stack component

Overlay replaces the reactions pattern

Additional removed props

​v0

​v1

​Migrate to updated hooks

​useCrmProperties updated to useRecordPropertiesCurrent

​useAssociations updated to useRecordAssociationsCurrent

​useCrmSearch updated to useRecordSearch

​New Stack component

​Overlay replaces the reactions pattern

​Dropdown uses children instead of options prop

​Additional removed props

v0

v1

Migrate to updated hooks

useCrmProperties updated to useRecordPropertiesCurrent

useAssociations updated to useRecordAssociationsCurrent

useCrmSearch updated to useRecordSearch

New Stack component

Overlay replaces the reactions pattern

Dropdown uses children instead of options prop

Additional removed props