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

# UI extensions SDK versioning

> Learn about how UI extensions SDK versions are released and how to upgrade to the latest version.

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](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration.md):

```shell theme={null}
npm install @hubspot/ui-extensions@^1
```

The sections below outline the changes made to [hooks](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks.md) and [components](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensions/ui-components/overview.md) 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:

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

> [tab] v0
>
> ```jsx theme={null}
>   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 },
>       },
>     }
>   );
> ```

> [tab] v1
>
> ```jsx theme={null}
>   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`.

> [tab] v0
>
> ```jsx theme={null}
>   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' } } }
>   );
> ```

> [tab] v1
>
> ```jsx theme={null}
>   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`.

> [tab] v0
>
> ```jsx theme={null}
>   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 } } }
>   );
> ```

> [tab] v1
>
> ```jsx theme={null}
> 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`](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/flex).

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

> [tab] v0
>
> ```jsx theme={null}
> <Button onClick={(event, reactions) => reactions.openPanel('my-panel')}>
>   Open
> </Button>
> <Panel id="my-panel">...</Panel>
> ```

> [tab] v1
>
> ```jsx theme={null}
> <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.

### Dropdown uses children instead of options prop

The `options` prop is removed from the `Dropdown` component. Instead, use `Dropdown.ButtonItem` child components to declare dropdown items.

> [tab] v0
>
> ```jsx theme={null}
> <Dropdown
>   buttonText="Actions"
>   options={[
>     { label: 'Edit', onClick: handleEdit },
>     { label: 'Delete', onClick: handleDelete },
>   ]}
> />
> ```

> [tab] v1
>
> ```jsx theme={null}
> <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` |