---
title: Configuration
category: reference
---

# Configuration

This page describes all available configuration options for `initializeLedgerProvider`. See [Get started](./get-started) for usage and [API reference](./api-reference) for the function signature.

## Configuration options

```typescript
{
  // Core options
  apiKey?: string;                                    // Your Ledger API key
  dAppIdentifier?: string;                            // Your dApp identifier
  loggerLevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug';  // Log verbosity (default: 'info')
  environment?: 'staging' | 'production';             // Target Ledger backend environment
  dmkConfig?: DeviceModuleOptions;                    // Device Management Kit configuration (optional)

  // UI options
  target?: HTMLElement;                               // Where to mount the UI (default: document.body)
  hideButton?: boolean;                               // Hide the floating button entirely (default: false)
  floatingButtonPosition?: 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center' | 'middle-right';  // Position of the floating button (default: 'bottom-right')
  floatingButtonTarget?: HTMLElement | string;        // Element or CSS selector to anchor the floating button to
  walletTransactionFeatures?: Array<'send' | 'receive' | 'swap' | 'buy' | 'earn' | 'sell'>;  // Wallet action CTAs to display

  // Development options
  devConfig?: {
    stub?: {
      base?: boolean;              // Enable base stub mode (default: false)
      account?: boolean;           // Stub account operations (default: false)
      balance?: boolean;           // Stub account balances (default: false)
      device?: boolean;            // Stub signer interactions (default: false)
      web3Provider?: boolean;      // Stub Web3 provider responses (default: false)
      dAppConfig?: boolean;        // Stub dApp configuration (default: false)
      transactionHistory?: boolean; // Stub transaction history (default: false)
    };
  };
}
```

All options are optional.

## Parameter details

### `apiKey`

Your Ledger API key. Required for production use.

### `dAppIdentifier`

Your dApp identifier. This lets Ledger validate the integration and enable remote services.

### `loggerLevel`

Log verbosity. Accepted values: `'fatal'`, `'error'`, `'warn'`, `'info'`, `'debug'`. Default is `'info'`.

### `environment`

Target Ledger backend environment. Accepted values: `'staging'`, `'production'`.

### `target`

Target element to mount the Ledger Wallet Provider UI. Defaults to `document.body`.

### `hideButton`

Hides the floating Ledger button entirely. Defaults to `false`.

When set to `true`, the floating button is not rendered on screen or inside a `floatingButtonTarget`. The Ledger UI (modal, side panel) is still mounted and the EIP-1193 provider is still registered — this is useful when you want to drive the flow exclusively from your own UI through the [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) provider.

```javascript
initializeLedgerProvider({
  hideButton: true,
  // ...
});
```

> **Note:** When `hideButton` is `true`, `floatingButtonPosition` and `floatingButtonTarget` have no effect.

### `floatingButtonPosition`

Controls where the floating Ledger button appears on screen. Default is `'bottom-right'`.

Available positions: `'bottom-right'`, `'bottom-left'`, `'bottom-center'`, `'top-right'`, `'top-left'`, `'top-center'`, `'middle-right'`.

```javascript
initializeLedgerProvider({
  floatingButtonPosition: "bottom-left",
  // ...
});
```

### `floatingButtonTarget`

An `HTMLElement` or CSS selector string. When provided, the floating button renders as a compact button inside the target element instead of being positioned on screen.

Use this to integrate the Ledger button into your own navigation bar, wallet panel, or sidebar.

```javascript
// CSS selector
initializeLedgerProvider({
  floatingButtonTarget: "#my-wallet-button-slot",
  // ...
});

// HTMLElement reference
initializeLedgerProvider({
  floatingButtonTarget: document.querySelector("#my-wallet-button-slot"),
  // ...
});
```

> **Note:** When `floatingButtonTarget` is set, `floatingButtonPosition` has no effect.
> The button is placed inside your target element instead.

### `walletTransactionFeatures`

An optional array of wallet transaction features to display as action buttons in the side panel.

Available features:

- `'send'` — Send crypto
- `'receive'` — Receive crypto
- `'swap'` — Swap tokens
- `'buy'` — Buy crypto
- `'earn'` — Earn rewards
- `'sell'` — Sell crypto

If not specified, the action buttons section is not displayed.

### `dmkConfig`

Device Management Kit configuration (optional). Passes custom device policies to the underlying Device Management Kit.

### `devConfig.stub`

Toggles local stub modes so you can simulate accounts, balances, devices, and Web3 flows during development without a physical signer.

| Field                | Default | Stubs                   |
| -------------------- | ------- | ----------------------- |
| `base`               | `false` | Base stub mode          |
| `account`            | `false` | Account operations      |
| `balance`            | `false` | Account balances        |
| `device`             | `false` | Signer interactions     |
| `web3Provider`       | `false` | Web3 provider responses |
| `dAppConfig`         | `false` | dApp configuration      |
| `transactionHistory` | `false` | Transaction history     |

```javascript
const cleanup = initializeLedgerProvider({
  devConfig: {
    stub: {
      base: true,
      account: true,
      balance: true,
      device: true,
      web3Provider: true,
      dAppConfig: true,
    },
  },
  dAppIdentifier: "my-dapp",
  apiKey: "your-api-key",
});
```

## Return value

`initializeLedgerProvider` returns a cleanup function. Call it to remove the provider and UI components from the DOM.

```typescript
const cleanup = initializeLedgerProvider({ /* options */ })

// Later, when unmounting:
cleanup()
```

The cleanup function removes the UI, deregisters the `eip6963:requestProvider` listener, and resets the internal provider state so a new configuration can be applied on the next call.

## See also

- [Get started](./get-started) — install the SDK and run your first integration
- [API reference](./api-reference) — `initializeLedgerProvider` function signature and `LedgerEIP1193Provider` methods
- [Requirements](./requirements) — browser and platform requirements