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

⚠️ On testnet, transactionOption.currency must be USDK as this is the only currency supported on testnet. You will need to switch the currency based on whether your app is currently using testnet or mainnet.

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

• Required: true

• Type: string

For more information see the Kima Transaction Backend section.

excludedSourceNetworks, excludedTargetNetworks

• 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"]}
/>

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

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.

Configure Kima Provider

Used to provide the widget with wallet connection, custom state handlers and backend endpoint.

kimaBackendUrl

Endpoint that will be used as intermediary to communicate with the kima blockchain. It's needed to fetch network mode, chains details and submit transactions through the sdk. 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

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

externalProvider

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

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.

logLevel

• Optional

• Type: LogLevel

  • trace

  • debug

  • info

  • warn

  • error (default)

  • silent

Specify the log level of the widget. Use this to help debug issues with the widget. The default is error. This can also be set via the ENV variable LOG_LEVEL or the libary specific variants NEXT_PUBLIC_LOG_LEVEL, VITE_LOG_LEVEL. The widget property will overwrite the ENV variable as it gets applied when the widget loads.

DEBUG mode: Type D E B U G while focus is on the Widget (not in the console) to enable debug mode. This will set the log level to debug and log all messages to the console. Type it again to disable debug mode and restore the default log level. Useful to temporarily toggle logging in the browser when in production or an already deployed app where changing the ENV variable would require a redeploy.