Choose your API

TokenFlight has two public APIs. They use the same config and callbacks.

• Use the HTML tag when your config is mostly strings.
• Use the JavaScript class when you need objects, functions, wallet adapters, or runtime state.
• If you are new and building React or Next.js, start with the JavaScript class.

Quick answer

Your app	Use this API	Why
Plain HTML, Vue, Svelte, Angular, Astro	<tokenflight-widget>	These frameworks handle custom elements well.
React client components	TokenFlightWidget	React 18 and older serialize object props as strings.
Next.js App Router or Pages Router	TokenFlightWidget in a client component	The widget needs the browser DOM.
Dynamic dashboards or checkout pages	TokenFlightWidget	You can mount, destroy, and rebuild from app state.

Option 1: HTML tag

The HTML tag is the shortest path. Register the element once, then place it in your page.

<tokenflight-widget
  theme="dark"
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
></tokenflight-widget>

<script type="module">
  import { registerWidgetElement } from '@tokenflight/swap/widget';

  registerWidgetElement();
</script>

For real crypto wallet actions, pass a walletAdapter to registerWidgetElement({ walletAdapter }). The HTML attributes can only hold strings; the adapter must come from JavaScript.

Use this when:

• You can express config as HTML attributes.
• You do not need per-instance JavaScript objects.
• Your framework supports Web Components cleanly.

Option 2: JavaScript class

The class gives you the most control. It is the recommended path for React and Next.js.

import { TokenFlightWidget } from '@tokenflight/swap';

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    theme: 'dark',
    toToken: {
      chainId: 8453,
      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
  },
  callbacks: {
    onDepositSuccess: (data) => {
      console.log('Payment complete:', data.orderId);
    },
  },
});

widget.initialize();

Use this when:

• You pass a wallet adapter.
• You pass callbacks or app functions.
• Config comes from React state, URL params, a cart, or your backend.
• You need to call destroy() during route changes.

Same model underneath

Both APIs use the same widget. The naming changes only because HTML attributes are strings.

HTML attribute	JavaScript config
to-token	toToken
from-token	fromToken
trade-type	tradeType
api-endpoint	apiEndpoint
fiat-api-endpoint	fiatApiEndpoint

Next step

Recommended path:

1. Pick the product behavior in Choose your flow.
2. Copy the closest framework shape from Examples.
3. Add the wallet adapter from AppKit, wagmi, ethers, or Custom Wallet Adapter.
4. Keep Troubleshooting open while you wire the first app.

Need every option? Use HTML Attributes or JavaScript API.