# Migration Guide

This guide covers migrating from MONEI Components v2 to v3. If you're starting fresh, see the [Components overview](https://docs.monei.com/monei-js/overview/.md) or go directly to your framework page.

## What's new in v3[​](#whats-new-in-v3 "Direct link to What's new in v3")

* **Dedicated framework packages** — `@monei-js/react-components`, `@monei-js/vue-components`, `@monei-js/angular-components`, `@monei-js/svelte-components`
* **`submit()` API** — call `submit()` directly on the component instance instead of `createToken()`
* **Typed props** — full TypeScript support for all component props and events
* **Svelte 5 support** — new `@monei-js/svelte-components` package
* **Payment Modal** — call `confirmPayment()` without a token to open a full checkout modal

## CDN URL change[​](#cdn-url-change "Direct link to CDN URL change")

```
- <script src="https://js.monei.com/v2/monei.js"></script>

+ <script src="https://js.monei.com/v3/monei.js"></script>
```

## npm package change[​](#npm-package-change "Direct link to npm package change")

```
- npm install @monei-js/components@1.x

+ npm install @monei-js/components@2.x
```

## Framework import changes[​](#framework-import-changes "Direct link to Framework import changes")

The `.driver()` API is replaced by dedicated framework packages. Each package exports native components — no more wrapping or bridging.

* Vanilla JS
* React
* Vue
* Angular
* Svelte

No import changes — vanilla JS uses `@monei-js/components` in both v2 and v3.

```
import {CardInput} from '@monei-js/components';



const cardInput = CardInput({paymentId: '...'});

cardInput.render('#card-input');
```

```
- import {CardInput, createToken} from '@monei-js/components';

- import React, {useRef} from 'react';

- const ReactCardInput = CardInput.driver('react', {React});

+ import {CardInput} from '@monei-js/react-components';
```

No longer needs `ReactDOM` or `findDOMNode` polyfill.

```
- import {CardInput, createToken} from '@monei-js/components';

- const MoneiCardInput = CardInput.driver('vue3');

+ import {CardInput} from '@monei-js/vue-components';
```

No more `__bridgeInstance` — use template refs directly.

```
- import {CardInput} from '@monei-js/components';

- import {Component, NgModule, ElementRef, NgZone, Inject} from '@angular/core';

- const CardInputModule = CardInput.driver('angular', {

-   Component, NgModule, ElementRef, NgZone, Inject

- });

+ import {MoneiCardInput} from '@monei-js/angular-components';
```

All components are standalone — no NgModule required. Uses typed `@Input()` bindings instead of an opaque `[props]` bag:

```
- <!-- Old: untyped props bag -->

- <bridge-component [props]="{paymentId: id, onChange: handler}"></bridge-component>

+ <!-- New: typed individual inputs -->

+ <monei-card-input

+   [paymentId]="id"

+   [accountId]="accountId"

+   [onChange]="handler"

+   [onFocus]="focusHandler"

+   [style]="inputStyle">

+ </monei-card-input>
```

New package — there was no previous Svelte driver.

```
import {CardInput} from '@monei-js/svelte-components';
```

Requires Svelte 5 (runes API).

## `createToken()` → `submit()` migration[​](#createtoken--submit-migration "Direct link to createtoken--submit-migration")

The standalone `createToken(instance)` function is replaced by `instance.submit()`. The return type is the same: `{token?: string, error?: string}`.

* Vanilla JS
* React
* Vue
* Angular
* Svelte

Before:

```
import {CardInput, createToken} from '@monei-js/components';



const cardInput = CardInput({paymentId: '...'});

cardInput.render('#card-input');

const {token} = await createToken(cardInput);
```

After:

```
import {CardInput} from '@monei-js/components';



const cardInput = CardInput({paymentId: '...'});

cardInput.render('#card-input');

const {token} = await cardInput.submit({cardholderName: 'John'});
```

Before:

```
import {createToken} from '@monei-js/components';



const ref = useRef(null);

const {token} = await createToken(ref.current, {cardholderName: 'John'});
```

After:

```
import {CardInput, type CardInputHandle} from '@monei-js/react-components';



const ref = useRef<CardInputHandle>(null);

const {token} = await ref.current!.submit({cardholderName: 'John'});
```

Before:

```
import {createToken} from '@monei-js/components';



const {token} = await createToken(cardInputRef.value.__bridgeInstance);
```

After:

```
import {CardInput} from '@monei-js/vue-components';



const cardInput = ref<InstanceType<typeof CardInput>>();

const {token} = await cardInput.value!.submit({cardholderName: 'John'});
```

Before:

```
// No typed submit() — had to access internal bridge instance
```

After:

```
import {MoneiCardInput} from '@monei-js/angular-components';



@ViewChild('cardInput') cardInput!: MoneiCardInput;

const {token} = await this.cardInput.submit({cardholderName: 'John'});
```

New package — use `bind:this` for component references:

```
<script lang="ts">

  import {CardInput} from '@monei-js/svelte-components';



  let cardInput: CardInput;



  async function handleSubmit() {

    const {token} = await cardInput.submit({cardholderName: 'John'});

  }

</script>



<CardInput bind:this="{cardInput}" {paymentId} />
```

## What's NOT changed[​](#whats-not-changed "Direct link to What's NOT changed")

note

`monei.api.createToken()` (used in [Apple Pay](https://docs.monei.com/payment-methods/apple-pay/.md) and [Google Pay](https://docs.monei.com/payment-methods/google-pay/.md) for wallet token exchange) is a **different API** and is not deprecated. Only the component-level `createToken(instance)` is deprecated.

## Deprecated APIs[​](#deprecated-apis "Direct link to Deprecated APIs")

The following APIs still work in v3 but log deprecation warnings in the console:

| Deprecated                  | Replacement                                  |
| --------------------------- | -------------------------------------------- |
| `.driver('react', {React})` | `import from '@monei-js/react-components'`   |
| `.driver('vue3')`           | `import from '@monei-js/vue-components'`     |
| `.driver('angular', {...})` | `import from '@monei-js/angular-components'` |
| `createToken(instance)`     | `instance.submit()`                          |

These deprecated APIs will be removed in a future major version.