Add the Kima Transaction Widget to a NextJS App

The procedure for adding the Kima Transaction Widget to a NextJS app is very similar to the React tutorial but you should be aware that you will need to export the widget component as a dynamic component with {ssr: false} so that the application runs the widget on the client side.

Assuming you are building an app from scratch, you can run npx create-next-app <your-app-name> to create a new app.

You can either run:

npm i @kimafinance/kima-transaction-widget

or else copy this package.json to the root of your directory and then simply run npm i.

Copy

{
  "name": "kima-next-minimal",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@kimafinance/kima-transaction-widget": "^1.1.98-beta.1",
    "next": "14.1.3",
    "pino-pretty": "^10.3.1",
    "react": "^18",
    "react-dom": "^18",
    "redux": "^5.0.1"
  },
  "devDependencies": {
    "autoprefixer": "^10.0.1",
    "eslint": "^8",
    "eslint-config-next": "14.1.3",
    "postcss": "^8",
    "tailwindcss": "^3.3.0"
  }
}

Within your app directory, create a components directory and inside that create a file named widget.jsx with the following code:

Copy

import dynamic from 'next/dynamic';
import React from 'react';

import {
  KimaTransactionWidget,
  KimaProvider,
  FontSizeOptions,
  ModeOptions,
  ColorModeOptions,
} from '@kimafinance/kima-transaction-widget';
import '@kimafinance/kima-transaction-widget/dist/index.css';

const App = () => {
  return (
    <KimaProvider>
      <div style={{ margin: '0 5vw' }}>
        <div className='container'>
          <KimaTransactionWidget
            theme={{
              colorMode: ColorModeOptions.light,
              fontSize: FontSizeOptions.medium,
            }}
            mode={ModeOptions.bridge}
            kimaBackendUrl='http://localhost:3001'
            kimaNodeProviderQuery='https://api-staging.kima.finance'
          />
        </div>
      </div>
    </KimaProvider>
  );
};

const DynamicApp = dynamic(() => Promise.resolve(App), {
  ssr: false,
});

export default DynamicApp;

You can now use DynamicApp on whatever page you like. In our example, we will create an index page index.jsx in our pages directory and copy the following code:

Copy

import React from 'react';
import DynamicApp from '../components/widget';

const HomePage = () => {
  return <DynamicApp />;
};

export default HomePage;

When you visit localhost:3000 you will see something like this:

Exactly as with the basic React implementation, you have all the same configuration options.

Configuration options

Note that in the above example, we have configured the title and payment title text, along with the colour. These are just some of the configuration options we describe below.

Configure the widget's look and feel

There are numerous ways to configure the modal for your own preferences and the look and feel of your dApp, which you can do via the following props:

Theme

The Theme prop allows you not only to switch between light and dark mode but also to specify your font colour and style and background colour:

Copy

  theme={{
    colorMode: ColorModeOptions.light,
    fontSize: FontSizeOptions.medium,
    fontFamily: 'Sans Serif',
    backgroundColorLight: '#CCCCCC', // background color of widget when light mode
    backgroundColorDark: '#FFDDFF' // background color of widget when dark mode
  }}

Title

The Title prop enables you to give the widget whatever title you want and can be configured for each step of the widget.

  • Required: false

  • Type: TitleOption:

Copy

titleOption={{
    initialTitle: 'New Purchase'
}}

Payment Title

The PaymentTitle prop allows you to optionally set the title that appears on the payment screen if you are using the Payment component.

  • Required: false

  • Type: PaymentTitleOption

Copy

 paymentTitleOption={{
   title:
     'You can now purchase our NFT on Polygon, using funds from other chains.',
   style: {
     fontSize: '1.2em',
     fontWeight: '500'
   }
 }}

HelpUrl

This is a string, which should be to your own help documentation or FAQ. If unset, the link will default to Kima's help documentation.

  • Required: false

  • Type: string

Configure the widget's functionality

Used to specify the scenario of kima-transaction-widget. Available modes are payment, bridget and status.

Required: true Type: ModeOptions Payment and bridge scenario for the purpose of widget, status mode is for tracking status of specific transaction of kima widget. To use status mode, txId prop should be determined export declare enum ModeOptions { payment = 'payment', bridge = 'bridge', status = 'status' }

TransactionOption

Within the payment scenario, you may optionally want to preset the chain and wallet address where the payment should go, as well as the payment amount.

  • Required: false

  • Type: TransactionOption

Copy

transactionOption={{
  targetChain: SupportNetworks.AVALANCHE, // target chain to receive payment
  targetAddress: '0x8222ADB2A2092c3774105a5F558987265D920C09', // target address to receive payment
  amount: 5 // USDK amount to receive payment
}}

kimaBackendUrl

This is one of the few props that is mandatory to set, because this specifies Kima's transaction back end URL. In the bridge example above, we have made the assumption that you have the back end server running locally on localhost:3001.

  • Required: true

  • Type: string

kimaNodeProviderQuery

Again, this is mandatory because this is used to specify the REST API URL for interactions with the Kima blockchain.

  • Required: true

  • Type: string

kimaExplorer

This is used to specify the URL of Kima's block explorer in the environment you are using. The widget needs this to provide updates to the status screen, as well as allowing users to link to their transactions to view progress.

It is not mandatory, but it is highly recommended.

Required: false Type: string Default: explorer.kima.finance

txID

Similarly, this is used to show users the progress of their transactions. It is not mandatory and is used only for status mode.

  • Required: false

  • Type: boolean

  • Default: -1

useFIAT

Used to specify whether users should be given the option to transact with fiat currency.

  • Required: false

  • Type: boolean

  • Default: false

autoConnect

This prop is optional and allows you to define whether connection of wallets such as MetaMask should be automatic or manual.

  • Required: false

  • Type: boolean

  • Default: false

Configure Kima Provider

Used to provide the widget with wallet connection and chain switching functionality.

walletConnectProjectId

Used to specify the WalletConnect project id. A default value is provided, but you can specify your own. To create a project, visit Reown Cloud and sign up for a free account (WalletConnect is now called Reown).

  • Required: false

  • Type: string

networkOption

Used to specify the network type.

  • Required: false

  • Type: NetworkOptions

  • Default: NetworkOptions.testnet

Last updated