---
title: Migration from V2 to V3
slug: technical-docs/migration-from-v2-to-v3
docTags: 
createdAt: 2026-03-31T11:31:13.861Z
---

# Overview

This guide explains how to migrate from IntelliWidgets V2 (JavaScript SDK) to IntelliWidgets V3, which is based on web components.

IntelliWidgets V3 introduces a simpler and more modern integration approach, reducing the amount of setup and JavaScript required to render widgets on your platform.

# Core concept

The main change in V3 is how widgets are integrated.

- **V2 (SDK)** uses a JavaScript API to create and mount widgets imperatively
- **V3 (Web Components)** uses native HTML elements to render widgets declaratively

In practice, this means:

- You no longer need to initialize an SDK instance
- You no longer mount widgets using selectors
- Widgets are placed directly in your HTML
- A shared `<ip-session>` component replaces the SDK instance and provides global configuration (such as authentication and language)

This shift makes integrations easier to maintain and avoids common issues such as CSS or script conflicts across different frameworks.

# Step-by-step migration

:::Heading{depth="3" indent="1"}
Replace the SDK script
:::

Remove the V2 SDK script:

```javascript
<script src="https://cdn.intelliprove.com/packages/intelli-widgets/v2/latest.js"></script>
```

Add the V3 script:

```html
<script type="module" src="https://cdn.intelliprove.com/packages/intelli-widgets/v3/latest.js"></script>
```

:::Heading{depth="3" indent="1"}
Remove SDK initalization
:::

In V2, you initialize the SDK:

```javascript
const intelli = IntelliProveWidgets("<USER_ACTION_TOKEN>");
```

In V3, this is replaced by the \<ip-session> component:

```html
<ip-session action-token="<USER_ACTION_TOKEN>">
  <!-- widgets go here -->
</ip-session>
```

The session component provides global configuration such as authentication and language.

:::Heading{depth="3" indent="1"}
Replace mountWidget with components
:::

In V2:&#x20;

```javascript
intelli.mountWidget("#biomarker", "biomarker", {
  face_scan_id: "...",
  parameter: "respiratory_rate"
});
```

In V3:

```html
<ip-biomarker
  face-scan-id="..."
  parameter="respiratory_rate">
</ip-biomarker>
```

Widgets are now rendered declaratively using HTML.

:::Heading{depth="3" indent="1"}
Wrap all widgets in session
:::

All IntelliProve web components must be placed within an \<ip-session>:

```html
<ip-session action-token="<USER_ACTION_TOKEN>">
  <ip-biomarker parameter="respiratory-rate"></ip-biomarker>
</ip-session>
```

This replaces the SDK instance and ensures all widgets share the same configuration.

:::Heading{depth="3" indent="1"}
Language handling
:::

In V2:

```javascript
intelli.changeLanguage("en");
```

In V3:

```html
<ip-session action-token="<USER_ACTION_TOKEN>" language="en">
```

:::Heading{depth="3" indent="1"}
Theming
:::

V3 widgets are built as web components, making them more flexible and customizable than in V2. Customization options are continuously being expanded.

If your V2 integration uses custom styling, you may need to adjust how these are applied in V3.

:::hint{type="info"}
For more information, refer to the [Theming](docId\:Wwt6QeJyzJVb5jNVzgmjc) page.
:::