Migration Guide

This guide covers migrating from MONEI Components v2 to v3. If you're starting fresh, see the Components overview or go directly to your framework page.

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

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

npm package change

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

Framework import changes

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

Vanilla JS

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');

React

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

Vue

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

Angular

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

Svelte

New package — there was no previous Svelte driver.

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

Requires Svelte 5 (runes API).

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

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'});

React

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'});

Vue

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'});

Angular

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'});

Svelte

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

note

monei.api.createToken() (used in Apple Pay and Google Pay for wallet token exchange) is a different API and is not deprecated. Only the component-level createToken(instance) is deprecated.

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.