💻Widget

Easily integrate Panora's swap functionality into your application with our lightweight, plug-and-play SDK — enabling seamless token swaps and real-time data directly within your platform.

Key Features

• Quick Setup — Add swaps to your app in under 5 minutes

• Three Display Modes — Integrated (inline), Widget (floating button), or Modal (popup)

• Fully Customizable — Theme colors, default tokens, locale, slippage, and more

• Multi-Language — Supports 11 locales out of the box

• Wallet Support — Built-in wallet connection UI, or bring your own

Display Modes

Mode	Description
INTEGRATED	Renders inline inside a target <div> you provide
WIDGET	Renders a floating button (configurable corner). Click to open the swap UI
MODAL	Opens a centered popup dialog with a backdrop overlay

Supported Frameworks

• Plain HTML / Vanilla JS

• React (Vite, CRA)

• Next.js (App Router & Pages Router)

• Any framework that can run JavaScript

Getting an API Key

A default public API key is available for development and typical usage:

a4^KV_EaTf4MW#ZdvgGKX#HUD^3IFEAOV_kzpIE^3BQGA8pDnrkT7JcIy#HNlLGi

For production or high-traffic use cases, open a ticket on Discord to request a dedicated key.

Installation

npm

npm install @panoraexch/widget-sdk

yarn

yarn add @panoraexch/widget-sdk

pnpm

pnpm add @panoraexch/widget-sdk

CDN (no bundler needed)

<script src="https://assets.panora.exchange/widget-v1.js" defer></script>

Quick Start

Option A: NPM (React / Next.js)

import { init, close } from "@panoraexch/widget-sdk";

// Open the widget
await init({
  displayMode: "INTEGRATED",
  integratedTargetId: "my-swap-container",
  panoraApiKey: "YOUR_API_KEY",
});

// Later, tear it down
close();

Option B: CDN (plain HTML)

<script src="https://assets.panora.exchange/widget-v1.js" defer></script>
<div id="my-swap-container"></div>

<script>
  window.addEventListener("load", function () {
    PanoraWidget.render("#my-swap-container", {
      displayMode: "INTEGRATED",
      panoraApiKey: "YOUR_API_KEY",
    });
  });
</script>

React App Example

A complete guide to integrating Panora Widget SDK into a React + Vite application.

1. Create a New Project

npm create vite@latest my-app -- --template react-ts
cd my-app

2. Install the SDK

npm install @panoraexch/widget-sdk

3. Add the Widget

Replace src/App.tsx with:

import { useEffect, useState } from "react";
import { init, close } from "@panoraexch/widget-sdk";

const API_KEY = import.meta.env.VITE_PANORA_API_KEY || "";
const DEFAULT_FROM = "0xa" as const;
const DEFAULT_TO =
  "0x..." as const;

type Tab = "INTEGRATED" | "WIDGET" | "MODAL";

export default function App() {
  const [activeTab, setActiveTab] = useState<Tab>("INTEGRATED");

  useEffect(() => {
    // Clean up any previous instance
    close();

    // MODAL is opened on-demand, not on mount
    if (activeTab === "MODAL") return;

    const timeout = setTimeout(() => {
      if (activeTab === "INTEGRATED") {
        init({
          panoraApiKey: API_KEY,
          displayMode: "INTEGRATED",
          integratedTargetId: "panora-widget-container",
          defaultFromTokenAddress: DEFAULT_FROM,
          defaultToTokenAddress: DEFAULT_TO,
          locale: "en",
          showNotifications: true,
        });
      } else if (activeTab === "WIDGET") {
        init({
          panoraApiKey: API_KEY,
          displayMode: "WIDGET",
          defaultFromTokenAddress: DEFAULT_FROM,
          defaultToTokenAddress: DEFAULT_TO,
          locale: "en",
          widgetBtnDirection: "right-bottom",
        });
      }
    }, 100);

    return () => {
      clearTimeout(timeout);
      close();
    };
  }, [activeTab]);

  return (
    <div>
      <h1>My App</h1>

      {/* ── Integrated Mode ── */}
      {activeTab === "INTEGRATED" && (
        <div id="panora-widget-container" />
      )}

      {/* ── Modal Mode — open / close on demand ── */}
      {activeTab === "MODAL" && (
        <div>
          <button
            onClick={() =>
              init({
                panoraApiKey: API_KEY,
                displayMode: "MODAL",
                defaultFromTokenAddress: DEFAULT_FROM,
                defaultToTokenAddress: DEFAULT_TO,
                locale: "en",
              })
            }
          >
            Open Swap Modal
          </button>
          <button onClick={() => close()}>Close</button>
        </div>
      )}
    </div>
  );
}

4. Run

npm run dev

Using the React Component

If you prefer a declarative approach instead of the imperative init() / close() API, the SDK also exports a <PanoraWidget /> React component:

import { PanoraWidget } from "@panoraexch/widget-sdk";

export default function App() {
  return (
    <PanoraWidget
      widgetConfig={{
        panoraApiKey: "YOUR_API_KEY",
        defaultFromTokenAddress: "0xa",
        defaultToTokenAddress:
          "0x...",
        locale: "en",
        showNotifications: true,
      }}
    />
  );
}

Note: <PanoraWidget /> always renders in INTEGRATED mode. For WIDGET or MODAL modes, use the imperative init() / close() API.

Key Points

• Always call close() before re-initializing to avoid duplicate instances

• The 100ms timeout gives the DOM time to settle before the widget mounts

• Store your API key in .env as VITE_PANORA_API_KEY

---

Next.js Example (App Router)

A complete guide to integrating Panora Widget SDK into a Next.js App Router application.

1. Create a New Project

npx create-next-app@latest my-app --typescript
cd my-app

2. Install the SDK

npm install @panoraexch/widget-sdk

3. Add the Widget

Create or replace src/app/page.tsx:

"use client";

import { useEffect, useState } from "react";
import { init, close } from "@panoraexch/widget-sdk";

const API_KEY = process.env.NEXT_PUBLIC_PANORA_API_KEY || "";
const DEFAULT_FROM = "0xa" as const;
const DEFAULT_TO =
  "0x..." as const;

export default function Home() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    setReady(true);
  }, []);

  useEffect(() => {
    if (!ready) return;

    init({
      panoraApiKey: API_KEY,
      displayMode: "INTEGRATED",
      integratedTargetId: "panora-widget-container",
      defaultFromTokenAddress: DEFAULT_FROM,
      defaultToTokenAddress: DEFAULT_TO,
      locale: "en",
      showNotifications: true,
    });

    return () => {
      close();
    };
  }, [ready]);

  return (
    <main>
      <h1>My App</h1>
      <div id="panora-widget-container" />
    </main>
  );
}

Important: The "use client" directive is required. The widget uses browser APIs (document, window) and cannot run during server-side rendering.

Widget Mode Example

"use client";

import { useEffect } from "react";
import { init, close } from "@panoraexch/widget-sdk";

export default function WidgetPage() {
  useEffect(() => {
    init({
      panoraApiKey: process.env.NEXT_PUBLIC_PANORA_API_KEY || "",
      displayMode: "WIDGET",
      widgetBtnDirection: "right-bottom",
      locale: "en",
    });

    return () => close();
  }, []);

  return (
    <main>
      <h1>Widget floating in the corner</h1>
    </main>
  );
}

Modal Mode Example

"use client";

import { init, close } from "@panoraexch/widget-sdk";

export default function ModalPage() {
  return (
    <main>
      <button
        onClick={() =>
          init({
            panoraApiKey: process.env.NEXT_PUBLIC_PANORA_API_KEY || "",
            displayMode: "MODAL",
            locale: "en",
          })
        }
      >
        Open Swap Modal
      </button>
      <button onClick={() => close()}>Close</button>
    </main>
  );
}

Next.js Pages Router

If you use the Pages Router instead of App Router, the code is nearly identical — just drop the "use client" directive and place your file in src/pages/index.tsx. No other changes needed.

Key Points

• Store your API key in .env.local as NEXT_PUBLIC_PANORA_API_KEY

• Always call close() in the useEffect cleanup to prevent memory leaks

• The widget loads its UI from the CDN at runtime, so your Next.js bundle size is unaffected

---

HTML App Example

The simplest integration — no bundler, no framework, just a single <script> tag.

1. Create an HTML File

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Panora Swap</title>
    <script src="https://assets.panora.exchange/widget-v1.js" defer></script>
  </head>
  <body>
    <h1>My App</h1>
    <div id="panora-widget-container"></div>

    <script>
      window.addEventListener("load", function () {
        PanoraWidget.render("#panora-widget-container", {
          panoraApiKey: "YOUR_API_KEY",
          displayMode: "INTEGRATED",
          defaultFromTokenAddress: "0xa",
          defaultToTokenAddress:
            "0x...",
          locale: "en",
          showNotifications: true,
        });
      });
    </script>
  </body>
</html>

2. Serve It

Use any static file server:

npx http-server .

Widget Mode (Floating Button)

<script>
  window.addEventListener("load", function () {
    PanoraWidget.render(document.body, {
      panoraApiKey: "YOUR_API_KEY",
      displayMode: "WIDGET",
      widgetBtnDirection: "right-bottom",
      locale: "en",
    });
  });
</script>

Modal Mode (Popup)

<button id="open-btn">Open Swap</button>

<script>
  var instance = null;

  document.getElementById("open-btn").addEventListener("click", function () {
    var root = document.getElementById("panora-widget-root");
    if (!root) {
      root = document.createElement("div");
      root.id = "panora-widget-root";
      document.body.appendChild(root);
    }

    instance = PanoraWidget.render(root, {
      panoraApiKey: "YOUR_API_KEY",
      displayMode: "MODAL",
      locale: "en",
    });
  });
</script>

API Reference (CDN)

When using the CDN script, the global PanoraWidget object is available on window:

Method	Description
PanoraWidget.render(container, config?)	Render the widget into a DOM element or CSS selector. Returns { unmount }

// container can be a DOM element or a CSS selector string
var instance = PanoraWidget.render("#my-div", { displayMode: "INTEGRATED" });

// To remove the widget:
instance.unmount();

Key Points

• The defer attribute ensures the script loads after HTML parsing

• PanoraWidget.render() accepts either a DOM element or a CSS selector (#id, .class)

• The CDN bundle is fully self-contained (includes React) — no other dependencies needed

---

Configuration

Complete reference for all WidgetConfig options.

API & RPC

Property	Type	Default	Description
panoraApiKey	string	Public key	Your Panora API key
rpcUrl	string	Panora default	Custom Aptos RPC URL. Must use https:// (except localhost)

Display

Property	Type	Default	Description
displayMode	"INTEGRATED" | "WIDGET" | "MODAL"	"WIDGET"	How the widget is presented
integratedTargetId	string	"panora-widget"	DOM element ID for INTEGRATED mode (used with init() only)
width	CSS value	450px (max)	Widget width in INTEGRATED mode
height	CSS value	630px	Widget height in INTEGRATED mode

Widget Button (WIDGET mode only)

Property	Type	Default	Description
widgetBtnSize	"SMALL" | "DEFAULT"	"DEFAULT"	Floating button size
widgetBtnDirection	"left-top" | "left-bottom" | "right-top" | "right-bottom"	"right-bottom"	Corner position
widgetBtnOffset	{ x: number; y: number }	—	Pixel offset from the corner

Tokens

Property	Type	Default	Description
defaultFromTokenAddress	`0x${string}`	—	Pre-selected "from" token
defaultToTokenAddress	`0x${string}`	—	Pre-selected "to" token
defaultFavoriteTokens	`0x${string}`[]	—	Tokens pinned as favorites in the token picker
customTokens	`0x${string}`[]	—	Additional token addresses shown in the picker
allowedTokens	`0x${string}`[]	—	Restrict the token list to only these addresses
showTokenCategorization	boolean	—	Show/hide token category tabs in the picker

Swap Settings

Property	Type	Default	Description
defaultSlippagePercentage	string	—	Default slippage tolerance (0–50). Must be a numeric string
showPercentageSlider	boolean	—	Show the percentage slider on the input field

Wallet

Property	Type	Default	Description
account	Account	undefined	Pre-configured Aptos account for direct transaction signing without wallet popup. Accepts any Account subclass from @aptos-labs/ts-sdk (Ed25519Account, SingleKeyAccount, KeylessAccount, etc.). When set, the widget signs transactions directly — no wallet connection needed.
independentWalletConnection	boolean	true	When false, hides the widget's built-in wallet connect button. Use when the host app manages wallet connection externally.
useExternalWallet	boolean	false	When true, the widget skips creating its own AptosWalletAdapterProvider and uses useWallet() from the nearest parent provider. The integrator must wrap the widget in their own <AptosWalletAdapterProvider>. Ideal for wallet extensions/apps embedding the widget. Only works with npm package (not CDN).
disableWalletButton	boolean	false	Hide the "Connect Wallet" button
enabledWallets	string[]	All wallets	Restrict which wallets appear in the connection dialog

Integrator Fees

Property	Type	Default	Description
integratorWalletAddress	`0x${string}`	—	Wallet address that receives integrator fees
integratorFeePercentage	number	—	Fee percentage per transaction (0–5)

Transaction Options

Property	Type	Default	Description
transactionOptions.maxGasAmount	number	—	Maximum gas units. Must be a positive integer
transactionOptions.gasUnitPrice	number	—	Price per gas unit (octas). Must be a positive integer

Localization

Property	Type	Default	Description
locale	string	"en"	UI language

Supported locales:

Code	Language
en	English
es	Spanish
hi	Hindi
id	Indonesian
ja	Japanese
ko	Korean
ru	Russian
tr	Turkish
vi	Vietnamese
zh	Chinese (Simplified)
zh-HK	Chinese (Traditional)

Notifications

Property	Type	Default	Description
showNotifications	boolean	false	Show toast notifications for swap success/failure

Validation Rules

The widget validates your config at runtime. Invalid values are silently ignored with a console warning:

Property	Rule
defaultSlippagePercentage	Must be a numeric string between 0 and 50
integratorFeePercentage	Must be a number between 0 and 5
rpcUrl	Must start with https:// (except localhost / 127.0.0.1)
transactionOptions.maxGasAmount	Must be a positive integer
transactionOptions.gasUnitPrice	Must be a positive integer

---

Theming

Customize the widget's appearance to match your app's design system.

Pass a partial theme object in your config — any property you omit will use the default Panora theme.

Usage

init({
  panoraApiKey: "YOUR_API_KEY",
  displayMode: "INTEGRATED",
  integratedTargetId: "panora-widget",
  theme: {
    primaryColor: "#6366f1",
    primaryButtonTextColor: "#ffffff",
    basicBgColor: "#1e1e2e",
    secondaryBgColor: "#181825",
    tertiaryBgColor: "#11111b",
    primaryTextColor: "#cdd6f4",
    secondaryTextColor: "#6c7086",
    borderColor: "#313244",
  },
});

Theme Properties

Property	Default	Description
basicBgColor	rgba(255, 255, 255, .05)	Primary background
secondaryBgColor	#010D09	Secondary background (outer areas)
tertiaryBgColor	#000704	Tertiary background (cards, dropdowns)
primaryColor	#5fdfac	Main accent color (buttons, highlights)
subtleColor	rgba(255, 255, 255, .05)	Subtle UI elements
primaryButtonTextColor	#000000	Text color on primary buttons
borderColor	rgba(255, 255, 255, .05)	Border color
inputColor	#0d110d	Input field background
inputBorderColor	#2a3a2a	Input field border
primaryTextColor	#FFFFFF	Main text color
secondaryTextColor	#6B7280	Muted/secondary text
placeholderTextColor	#3a4a3a	Input placeholder text
textUpColor	#5fdfac	Positive values (gains)
textDownColor	#F6465D	Negative values (losses)
successColor	#5fdfac	Success states
errorColor	#F6465D	Error states
warningColor	#EF8E19	Warning states

Default Theme

{
  "id": "panora",
  "name": "Panora",
  "basicBgColor": "rgba(255, 255, 255, .05)",
  "secondaryBgColor": "#010D09",
  "tertiaryBgColor": "#000704",
  "primaryColor": "#5fdfac",
  "subtleColor": "rgba(255, 255, 255, .05)",
  "primaryButtonTextColor": "#000000",
  "borderColor": "rgba(255, 255, 255, .05)",
  "inputColor": "#0d110d",
  "inputBorderColor": "#2a3a2a",
  "primaryTextColor": "#FFFFFF",
  "secondaryTextColor": "#6B7280",
  "placeholderTextColor": "#3a4a3a",
  "textUpColor": "#5fdfac",
  "textDownColor": "#F6465D",
  "successColor": "#5fdfac",
  "errorColor": "#F6465D",
  "warningColor": "#EF8E19"
}

Tip: You can import the default theme object in code:

import { DEFAULT_WIDGET_THEME } from "@panoraexch/widget-sdk";

---

API Reference

NPM Package Exports

// Functions
import { init, render, close, resume } from "@panoraexch/widget-sdk";

// React component
import { PanoraWidget } from "@panoraexch/widget-sdk";

// Constants
import { DEFAULT_WIDGET_THEME } from "@panoraexch/widget-sdk";

// Types
import type {
  WidgetConfig,
  PanoraWidgetConfig, // backward-compatible alias for WidgetConfig
  AppTheme,
  WidgetFeature,
  WidgetTheme,
  PanoraWidgetProps,
} from "@panoraexch/widget-sdk";

init(config?)

Initialize and render the widget.

function init(
  config?: WidgetConfig & { integratedTargetId?: string }
): Promise<{ unmount: () => void }>

Parameter	Type	Description
config	WidgetConfig	Widget configuration (see Configuration)
config.integratedTargetId	string	DOM element ID for INTEGRATED mode. Defaults to "panora-widget"

Returns: Promise<{ unmount: () => void }> — call unmount() to remove the widget.

Behavior by display mode:

Mode	What happens
INTEGRATED	Renders into the element matching integratedTargetId. Throws if element not found.
WIDGET	Creates a floating button. A panora-widget-root container is auto-created in document.body if needed.
MODAL	Opens a centered dialog with backdrop. Container auto-created like WIDGET.

render(container, config?)

Lower-level alternative to init() for full control over where the widget mounts.

function render(
  container: HTMLElement | string,
  config?: WidgetConfig
): Promise<{ unmount: () => void }>

Parameter	Type	Description
container	HTMLElement | string	A DOM element or CSS selector ("#my-div", ".my-class")
config	WidgetConfig	Widget configuration

Note: render() is primarily used with the CDN bundle (PanoraWidget.render()). When using the npm package, prefer init().

close()

Unmount and clean up the widget.

function close(): void

Always call close() before re-initializing, or in your component's cleanup function to prevent duplicate instances.

resume()

Re-show the widget with the last configuration passed to init().

function resume(): Promise<void>

If a widget instance is already mounted, this is a no-op.

<PanoraWidget />

React component for declarative rendering. Always uses INTEGRATED mode.

interface PanoraWidgetProps {
  widgetConfig?: WidgetConfig;
}

<PanoraWidget
  widgetConfig={{
    panoraApiKey: "YOUR_API_KEY",
    locale: "en",
  }}
/>

• Automatically creates a container <div> and calls init() on mount

• Automatically calls close() on unmount

• Re-initializes when widgetConfig changes

CDN Global: PanoraWidget

When using the CDN <script> tag, a global PanoraWidget object is available on window.

window.PanoraWidget.render(
  container: HTMLElement | string,
  config?: WidgetConfig
): { unmount: () => void }

Parameter	Type	Description
container	HTMLElement | string	DOM element or CSS selector
config	WidgetConfig	Widget configuration

The CDN bundle is fully self-contained — it includes its own copy of React and all dependencies.

---

Attribution

Include "Powered by Panora" when using this SDK in your application. The widget displays this by default.