Configuration

This page describes all available configuration options for initializeLedgerProvider. See Get started for usage and API reference for the function signature.

Configuration options

{
  // 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)
  blockchainProviderFactories?: BlockchainProviderFactoryRegistration[]; // Family factories to register (required for EVM / Solana)
 
  // 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
  transactionConfirmationNotification?: 'tooltip' | 'toast';  // How TX confirmation is shown (default: 'tooltip')
 
  // 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)
      solanaProvider?: boolean;    // Stub Solana provider responses (default: false)
      transactionHistory?: boolean; // Stub transaction history (default: false)
    };
  };
}

All options are optional. Pass blockchainProviderFactories for any chain provider to load.

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.

blockchainProviderFactories

Host-supplied factories that create blockchain providers. Required for any family to load — the UI package never imports family packages itself.

Install the family package, import its factory, and register it against the family it serves:

import { initializeLedgerProvider } from "@ledgerhq/ledger-wallet-provider";
import { createEvmBlockchainProvider } from "@ledgerhq/ledger-wallet-provider-evm";
import { createSolanaBlockchainProvider } from "@ledgerhq/ledger-wallet-provider-solana";
 
initializeLedgerProvider({
  dAppIdentifier: "my-dapp",
  apiKey: "your-api-key",
  blockchainProviderFactories: [
    { family: "ethereum", create: createEvmBlockchainProvider },
    { family: "solana", create: createSolanaBlockchainProvider },
  ],
});

A factory is skipped when that family is not enabled in your partner dApp configuration. If you omit blockchainProviderFactories (or pass an empty array), no EVM or Solana provider is registered.

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 any providers you registered via blockchainProviderFactories are still announced — this is useful when you want to drive the flow exclusively from your own UI (for example through the EIP-6963  provider).

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

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

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.

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

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.

transactionConfirmationNotification

Controls how transaction confirmation feedback is shown after a signing flow. Default is 'tooltip'.

Accepted values:

• 'tooltip' — show confirmation on the floating button (badge / tooltip)
• 'toast' — show confirmation as a toast notification

initializeLedgerProvider({
  transactionConfirmationNotification: "toast",
  // ...
});

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.

const cleanup = initializeLedgerProvider({
  devConfig: {
    stub: {
      base: true,
      account: true,
      balance: true,
      device: true,
      web3Provider: true,
      solanaProvider: 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.

const cleanup = initializeLedgerProvider({ /* options */ })
 
// Later, when unmounting:
cleanup()

The cleanup function removes the UI, deregisters any providers that were registered for your partner configuration (for example the EVM eip6963:requestProvider listener and/or the Solana Wallet Standard wallet), and resets internal provider state so a new configuration can be applied on the next call.

See also

• Get started — install the SDK and run your first integration
• API reference — initializeLedgerProvider function signature and LedgerEIP1193Provider (from @ledgerhq/ledger-wallet-provider-evm)
• Requirements — browser and platform requirements