# Configuration Options

## Configuration options <a href="#configuration-options" id="configuration-options"></a>

### Configure the widget's look and feel <a href="#configure-the-widgets-look-and-feel" id="configure-the-widgets-look-and-feel"></a>

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

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

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

```tsx
<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 <a href="#configure-the-widgets-functionality" id="configure-the-widgets-functionality"></a>

* Required: true
* Type: ModeOptions
  * payment: [Payment scenario](/kima-network/the-kima-sdk/add-kima-widget-to-your-app/widget-payment-mode.md)
  * bridge: [Bridge scenario](/kima-network/the-kima-sdk/add-kima-widget-to-your-app/widget-bridge-mode.md)
  * status: mode for [tracking the status](/kima-network/the-kima-sdk/add-kima-widget-to-your-app/widget-status-mode.md) 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
  * sourceChain (optional): ChainName
  * targetChain (required): ChainName
  * targetAddress (required): string
  * amount (required): number
  * currency (required): string

> ⚠️ `transactionOption.currency` must be a token symbol supported by Kima for the selected environment (`mainnet` or `testnet`) and target chain. Resolve valid symbols dynamically from your backend `/chains` response.

```tsx
import {
  ChainName,
  KimaProvider,
  KimaTransactionWidget,
} from "@kimafinance/kima-transaction-widget";

<KimaProvider
  projectId="your-project-id"
  kimaBackendUrl="http://localhost:4000"
>
  <KimaTransactionWidget
    transactionOption={{
      targetChain: ChainName.AVALANCHE,
      targetAddress: "0x8222ADB2A2092c3774105a5F558987265D920C09",
      amount: 5,
      currency: "USDC",
    }}
  />
</KimaProvider>;
```

#### `txId`

Used in Status mode to specify the transaction to track progress for. If omitted in Status mode, the widget will display the transaction search form instead.

* Status mode: Optional
* Type: `number | string`
* Default: unset

## Compliance

**`compliantOption`**

* Required: `false`
* Type: `boolean`
* Default: `false`

If your app requires compliance checks, please contact us at <support@kima.finance> for more information. When `false` (the default), compliance checks are disabled. When enabled, checks are made to determine if an address meets compliance requirements, for example whether it is sanctioned or blocked. A failed compliance check results in the transaction being rejected. See the Compliance section in the [Kima Transaction Backend](/kima-network/the-kima-sdk/the-kima-transaction-back-end.md#compliance)

## Configure Kima Provider <a href="#configure-kima-provider" id="configure-kima-provider"></a>

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 is needed to fetch the active environment, chain details, and submit transactions through the SDK. This is one of the few props that is mandatory to set, because there are several endpoints which the widget expects to exist on the backend. The examples assume the backend server is exposed locally at `localhost:4000`. Replace this with the URL of your backend.

Port note: the backend itself commonly runs on `localhost:3001`, but some local frontend setups expose or proxy it on `localhost:4000`. Always use the actual URL and port where your backend is reachable from the app that embeds the widget.

* Required: `true`
* type: `string`

### `projectId`

Used to specify the Reown project id. Visit [Reown Cloud](https://cloud.reown.com/sign-in) and sign up for a free account to obtain a project id.

* Required: `true`
* Type: `string`

### `solRPC`

Optional custom Solana RPC endpoint passed into the widget provider. Use this if you want the widget to use your own Solana RPC instead of the default provider.

* Required: `false`
* Type: `string`

Example:

```tsx
<KimaProvider
  projectId="your-project-id"
  kimaBackendUrl="http://localhost:4000"
  solRPC="https://your-solana-rpc.example"
>
  <KimaTransactionWidget
    theme={{ colorMode: ColorModeOptions.light }}
    mode={ModeOptions.bridge}
  />
</KimaProvider>
```

### `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 library-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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kima.network/kima-network/the-kima-sdk/add-kima-widget-to-your-app/configure-kima-widget.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.