thirdwebDocs
Bridge

BridgeWidget Script

The BridgeWidget Script makes it easy to embed cross-chain swaps and fiat onramp UI into your app. Just add a script tag to your HTML and get a fully customizable widget — no build setup required.

Key Features

  • Cross-chain token swaps across 80+ blockchains
  • Fiat onramp support to buy tokens with credit/debit cards
  • Customizable UI - use prebuilt themes or override with your brand colors
  • Prefill token selections for a smoother user experience
  • Display fiat values in multiple currencies
  • Event callbacks to track user actions (success, error, cancel, disconnect)

Script Integration

<!-- Add this script in <head> -->
<script src="https://unpkg.com/thirdweb/dist/scripts/bridge-widget.js"></script>
 
<!-- Add a container element where you want to render the UI -->
<div id="bridge-widget-container"></div>
 
<!-- Initialize the widget at the end of <body> -->
<script>
  const container = document.querySelector('#bridge-widget-container');
 
  BridgeWidget.render(container, {
    clientId: "your-thirdweb-client-id",
    theme: "dark",
    buy: {
      chainId: 8453,
      amount: "0.1",
    },
  });
</script>

Options

You can customize theme, currencies, token selections, and more. See the full list of options below

clientId

Set your Project's client ID to identify your project. You create a project for free on thirdweb dashboard

swap

The options to configure the "Swap" tab

type Swap = {
  className?: string;
  style?: React.CSSProperties;
  onSuccess?: (quote: SwapPreparedQuote) => void;
  onError?: (error: Error, quote: SwapPreparedQuote) => void;
  onCancel?: (quote: SwapPreparedQuote) => void;
  onDisconnect?: () => void;
  persistTokenSelections?: boolean;
  prefill?: {
    buyToken?: {
      tokenAddress?: string;
      chainId: number;
      amount?: string;
    };
    sellToken?: {
      tokenAddress?: string;
      chainId: number;
      amount?: string;
    };
  };
};

buy

The options to configure the "Buy" tab UI.

type Buy = {
  amount: string; // Required
  chainId: number; // Required
  tokenAddress?: string;
  buttonLabel?: string;
  onCancel?: (quote: BuyOrOnrampPrepareResult | undefined) => void;
  onError?: (
    error: Error,
    quote: BuyOrOnrampPrepareResult | undefined,
  ) => void;
  onSuccess?: (quote: BuyOrOnrampPrepareResult) => void;
  className?: string;
  country?: string;
  presetOptions?: [number, number, number];
};

theme

Set the theme for the widget. You can either set it to "dark", "light" or overrides some or all the colors by passing an object. By default it set to "dark".

When overriding the colors, you must set the type to either "dark" or "light" so that the widget knows which theme to apply the overrides to.

type Theme =
  | "dark"
  | "light"
  | {
      type: "dark" | "light"; // required
      accentButtonBg?: string;
      accentButtonText?: string;
      accentText?: string;
      borderColor?: string;
      connectedButtonBg?: string;
      connectedButtonBgHover?: string;
      danger?: string;
      inputAutofillBg?: string;
      modalBg?: string;
      modalOverlayBg?: string;
      primaryButtonBg?: string;
      primaryButtonText?: string;
      primaryText?: string;
      scrollbarBg?: string;
      secondaryButtonBg?: string;
      secondaryButtonHoverBg?: string;
      secondaryButtonText?: string;
      secondaryIconColor?: string;
      secondaryIconHoverBg?: string;
      secondaryIconHoverColor?: string;
      secondaryText?: string;
      selectedTextBg?: string;
      selectedTextColor: string;
      separatorLine?: string;
      skeletonBg: string;
      success?: string;
      tertiaryBg?: string;
      tooltipBg?: string;
      tooltipText?: string;
    };

Example

BridgeWidget.render(container, {
  clientId: "your-thirdweb-client-id",
  theme: {
    type: "dark",
    colors: {
      modalBg: "black",
      primaryText: "white",
    },
  },
});

currency

The token amounts fiat values will be displayed in this currency. By default, it is set to "USD".

type Currency =
  | "USD"
  | "EUR"
  | "GBP"
  | "JPY"
  | "KRW"
  | "CNY"
  | "INR"
  | "NOK"
  | "SEK"
  | "CHF"
  | "AUD"
  | "CAD"
  | "NZD"
  | "MXN"
  | "BRL"
  | "CLP"
  | "CZK"
  | "DKK"
  | "HKD"
  | "HUF"
  | "IDR"
  | "ILS"
  | "ISK";

showThirdwebBranding

Whether to show thirdweb branding at the bottom of the widget. By default, it is set to true.