Configuration Options

Configuration options

Configure the widget's look and feel

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

Theme

The Theme prop controls whether the Widget is in light or dark mode and their background colours:

• Required

• Type: ThemeOptions

  • colorMode (required): ColorModeOptions.light | ColorModeOptions.dark

  • backgroundColorLight (optional): string

  • backgroundColorDark (optional): string

  <KimaTransactionWidget
    theme={{
      colorMode: ColorModeOptions.light,
      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.

• Optional

• Type: TitleOption:

  • initialTitle (optional): string

  • confirmTitle (optional): string

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

• Optional

• Type: PaymentTitleOption

  • title (optional): string

  • style (optional): object

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

• Optional

• Type: string

mode: Configure the widget's functionality

• Required: true

• Type: ModeOptions

  • payment: Payment scenario

  • bridge: Bridge scenario

  • status: mode for tracking the status of a specific Kima transaction

Used to specify the transaction flow scenario of the Widget. See the individual scenarios for more information.

TransactionOption

Sets the default chain, wallet, and amount in the Widget. Required for the Payment mode, optional for the Bridge mode.

• Payment mode: Required, Bridge mode: Optional

• Type: TransactionOption

  • targetChain (optional): SupportNetworks

  • targetAddress (optional): string

  • amount (optional): number

  • currency (optional): string

import { SupportNetworks } from '@kimafinance/kima-transaction-widget'

  <KimaTransactionWidget
    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 there are several enpoints which the Widget expects to exist on the Backend. The examples assume the backend server is running locally at localhost:3001. Replace this with the URL of your backend.

• Required: true

• Type: string

For more information see the Kima Transaction Backend section.

kimaExplorer

• Optional

• Type: string

• Default: explorer.kima.network

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.

• Kima Mainnet Explorer: https://explorer.kima.network

• Sardis (Testnet) Explorer: https://explorer.sardis.kima.network

excludeedSourceNetworks, excludeedTargetNetworks

• Optional

• Type: string[]

• Default: []

Chain names to exlude from the widget. Users will not be able to select these chains in the widget. Useful for compliance reasons or to exclude chains not supported by your app.

There is currently no opton to do the opposite- i.e. explicity specify which chains to include.

Excluded target networks will have no effect in payment mode as the target chain, address, and amount are already explicity set.

  <KimaTransactionWidget
    excludedSourceNetworks={['TRX', 'BSC']}
    excludedTargetNetworks={['ETH']}
  />

errorHandler

• Optional

• Type: function

Called when an error occurs. Useful for debugging and logging.

closeHandler

• Optional

• Type: function

Called when the widget is closed.

successHandler

• Optional

• Type: function

Called when the transaction is successful.

txID

Used in Status mode to specify the transaction to track progress for. Only used in status mode, ignored otherwise.

• Status mode: Required, ignored otherwise

• Type: boolean

• Default: -1

Configure Kima Provider

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

walletConnectProjectId

Used to specify the WalletConnect project id. Visit Reown Cloud and sign up for a free account (WalletConnect is now called Reown) to obtain a project id.

• Required: true

• Type: string

networkOption

Used to specify the network type.

• Required: false

• Type: NetworkOptions

• Default: NetworkOptions.testnet

extneralProvider

If there is already a wallet connection logic elsewhere in your app, an external provider can be passed in. Otherwise, the widget will handle the connection logic on its own.

• Required: false

• Type: ExternalProvider

Compliance

compliantOption

• Required: false

• Type: boolean

• Default: false

If your app requires compliance checks, please contact us for more information. When false (the default), compliance checks are disabled.