WalletButton

WalletButton is the prebuilt connect button from @xrpl-wallet-kit/ui. It handles the full connect → display address → account panel → disconnect lifecycle automatically.

Basic usage

import { WalletManager } from "@xrpl-wallet-kit/core";
import { WalletModal, WalletButton } from "@xrpl-wallet-kit/ui";

const manager = new WalletManager({ adapters: [/* ... */], network: "mainnet" });
const modal   = new WalletModal({ manager });

const button = new WalletButton({
  manager,
  modal,
  target: document.getElementById("connect-btn-root")!,
});

html

<!-- Place in your HTML -->
<div id="connect-btn-root"></div>

That's it. The button shows "Connect Wallet" when disconnected and the truncated address when connected. Clicking the address opens an account panel with copy, QR, and disconnect options.

Options reference

interface WalletButtonOptions {
  // Required
  manager: WalletManager;
  modal:   WalletModalController;

  // Target element — where to mount the button
  target?: string | HTMLElement;    // CSS selector string or HTMLElement

  // Label shown while disconnected
  label?: string;                   // default: "Connect Wallet" (localized)
  icon?: WalletButtonIconConfig;    // disconnected-state icon (default: built-in wallet icon)

  // Connected-state display
  showAdapterIcon?: boolean;        // show wallet logo next to address (default: true)
  showChevron?: boolean;            // show ▾ chevron on the button (default: true)
  showWeb3Name?: boolean;           // show xrpdomains.xyz name if resolved (default: true)
  fallbackToAddress?: boolean;      // fall back to address if no name resolved (default: true)
  formatAddress?: (addr: string) => string;   // custom address display format

  // Account panel actions
  copyAddress?: boolean;            // show copy address action (default: true)
  showAddressQr?: boolean;          // show QR code in account panel (default: true)
  explorer?: boolean;               // show block explorer link (default: false)
  explorerUrl?: (session: WalletSession) => string | undefined;
  disconnect?: boolean;             // show disconnect action (default: true)

  // Account panel behavior
  accountPanel?: boolean;           // enable account panel (default: true)
  accountPanelMode?: "dropdown" | "modal";    // default: "modal"

  // Balance display
  showBalance?: boolean;            // native balance in button/panel (default: false)
  balanceResolver?: WalletBalanceResolver;    // custom balance fetcher

  // Recent transactions
  showRecentTransactions?: boolean; // show recent txs in account panel (default: false)
  maxVisibleTransactions?: number;  // max rows to show before internal scroll (default: 5)
  transactionExplorerUrl?: (hash: string, network?: WalletNetwork) => string | undefined;

  // Identity (web3 name)
  identityResolver?: WalletIdentityResolver; // custom name resolver

  // Size & variant
  size?: "sm" | "md" | "lg";       // default: "md"
  variant?: "default" | "pill" | "minimal" | "outline";  // default: "default"

  // Theming
  themeMode?: "light" | "dark" | "auto";     // default: "light"
  themeName?: "default" | "light" | "dark" | "xrpl" | "minimal" | "midnight" | "glass" | "rounded" | "crisp" | "soft";
  theme?: WalletUiTheme;            // token overrides (see Theming)
  customTheme?: WalletUiTheme;      // token overrides applied after theme

  // Localization
  language?: WalletUiLocale;
  messages?: WalletUiMessagesInput;

  // Callbacks
  onIdentityChange?: (identity: WalletIdentity | null, session: WalletSession | null) => void;
  onBalanceChange?: (balance: WalletBalance | null, session: WalletSession | null) => void;
}

type WalletButtonIconConfig =
  | { type: "default" }
  | { type: "image"; src: string; alt?: string }
  | { type: "html"; html: string; ariaLabel?: string };

Size variants

// Small — 32px height, suitable for navigation bars
const button = new WalletButton({ manager, modal, target, size: "sm" });

// Default — 40px height (default)
const button = new WalletButton({ manager, modal, target, size: "md" });

// Large — 48px height, prominent CTAs
const button = new WalletButton({ manager, modal, target, size: "lg" });

Style variants

// Default — solid accent-colored background
const button = new WalletButton({ manager, modal, target, variant: "default" });

// Pill — rounded-full border-radius
const button = new WalletButton({ manager, modal, target, variant: "pill" });

// Minimal — transparent background, text only
const button = new WalletButton({ manager, modal, target, variant: "minimal" });

// Outline — border only, no fill
const button = new WalletButton({ manager, modal, target, variant: "outline" });

Custom disconnected icon

By default, the disconnected button shows the kit's built-in wallet SVG because showAdapterIcon defaults to true and icon defaults to { type: "default" }.

Use icon only when the disconnected button should use your app or brand mark instead of the built-in wallet glyph. This only affects the pre-connect state. After a wallet connects, the button still prefers the active wallet/account icon.

const button = new WalletButton({
  manager,
  modal,
  target,
  label: "Connect",
  icon: {
    type: "image",
    src: "/brand-wallet.svg",
    alt: "MyApp wallet",
  },
});

To hide the button icon entirely, set showAdapterIcon: false:

const button = new WalletButton({
  manager,
  modal,
  target,
  showAdapterIcon: false,
});

For advanced branding, pass trusted inline HTML. Keep it compact; the icon slot is fixed to avoid button layout shifts.

const button = new WalletButton({
  manager,
  modal,
  target,
  icon: {
    type: "html",
    ariaLabel: "MyApp",
    html: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="..." /></svg>',
  },
});

Account panel mode

// Dropdown — panel appears directly below the button (explicit opt-in)
const button = new WalletButton({
  manager,
  modal,
  target,
  accountPanelMode: "dropdown",
});

// Modal — account panel opens as a centered overlay
const button = new WalletButton({
  manager,
  modal,
  target,
  accountPanelMode: "modal",
});

Balance display

Balance display is off by default. Enable it to show the selected network's native asset (XRP or XAH) in the button and account panel. The default resolver displays the available balance after reserves and keeps total/reserve details in the panel. Formatting uses fewer decimals for larger balances.

When the host constrains the button width, Kit hides the inline balance before it wraps; the account panel still shows it. Avoid CSS that forces Kit's balance onto a separate line or overrides its visibility. Requests for the same active balance are shared; a transient refresh failure retains the previous value.

const button = new WalletButton({
  manager,
  modal,
  target,
  showBalance: true,
  // Optional: supply a custom balance resolver
  balanceResolver: async ({ address, network, signal }) => {
    const value = await myBalanceApi.getBalance(address, network?.id, signal);
    const symbol = network?.nativeAsset ?? "XRP";
    return { value, formatted: `${value} ${symbol}`, symbol };
  },
});

Browser balance reads use network.httpRpcUrl. Choose an endpoint that permits your origin or provide your own resolver through a trusted backend. The Xahau protocol's xahau.request override does not replace the balance resolver. Call kit.refreshBalance() or button.refreshBalance() after external activity; avoid repeatedly refreshing from a render loop.

Recent transactions

Recent transactions are off by default. Enable them when you want the account panel to show submitted, confirmed, failed, or unknown transactions for the connected account.

const button = new WalletButton({
  manager,
  modal,
  target,
  showRecentTransactions: true,
  maxVisibleTransactions: 5,
});

See Recent Transactions for automatic tracking, manual entries, statuses, and explorer link configuration.

Custom identity (web3 name)

By default, the button uses createXrpDomainsResolver() to look up the address in xrpdomains.xyz. Supply your own resolver to use a different name registry:

import { WalletButton } from "@xrpl-wallet-kit/ui";

const button = new WalletButton({
  manager,
  modal,
  target,
  identityResolver: async (address, session) => {
    const name = await myNameRegistry.lookup(address);
    return name ? { name, source: "my-registry" } : null;
  },
  onIdentityChange: (identity, session) => {
    console.log("Name resolved:", identity?.name);
  },
});

Custom explorer link

const button = new WalletButton({
  manager,
  modal,
  target,
  explorer: true,
  explorerUrl: (session) =>
    `https://bithomp.com/explorer/${session.account.address}`,
});

Theming

The button inherits from the same token system as WalletModal:

const button = new WalletButton({
  manager,
  modal,
  target,
  themeMode: "dark",
  themeName: "midnight",
  theme: {
    accent: "#7c3aed",
    accentText: "#ffffff",
    success: "#34d399",
    radius: "999px",   // fully rounded
    fontFamily: "'Inter', sans-serif",
  },
});

See Theming for the full token list.

Update options at runtime

button.updateOptions({
  themeMode: "dark",
  showBalance: true,
});

Mount/unmount

// Re-mount to a different element
button.mount(document.getElementById("new-target")!);

// Destroy and remove from DOM
button.destroy();

`createWalletKit` shorthand

If you're using the all-in-one package, the button is created automatically:

import { createWalletKit } from "@xrpl-wallet-kit/client";

const kit = createWalletKit({
  adapters: [/* ... */],
  connectButton: {
    target: "#connect-btn-root",
    size: "md",
    variant: "pill",
    showBalance: true,
    showRecentTransactions: true,
    icon: {
      type: "image",
      src: "/brand-wallet.svg",
      alt: "MyApp wallet",
    },
    themeMode: "dark",
  },
});

// Access the button instance
kit.button.updateOptions({ themeMode: "light" });

WalletButton ​

Basic usage ​

Options reference ​

Size variants ​

Style variants ​

Custom disconnected icon ​

Account panel mode ​

Balance display ​

Recent transactions ​

Custom identity (web3 name) ​

Custom explorer link ​

Theming ​

Update options at runtime ​

Mount/unmount ​

createWalletKit shorthand ​

See also ​