Introduction - Superbridge Docs

Getting Started

A drop-in React component that adds cross-chain bridging and swapping to your application

The Superbridge Widget is a drop-in React component that adds cross-chain bridging and swapping to your application.

Installation

npm install @superbridge/widget

Peer dependencies

The widget requires the following peer dependencies:

react >= 19
react-dom >= 19
wagmi >= 3
@tanstack/react-query >= 5

Quick start

import { Widget } from "@superbridge/widget";
import "@superbridge/widget/styles.css";

function App() {
  return <Widget />;
}

Props

All props are optional. The full set is typed by WidgetProps exported from @superbridge/widget — your editor will autocomplete and document them inline. The most common ones:

Appearance

Prop	Type	Description
`theme.cssVariables`	`WidgetCssVariables`	CSS variable overrides for colors, fonts, radius, and per-shape tokens. See Theming.
`theme.motion`	`MotionProps`	Per-element hover/tap/open transitions. See Theming.
`theme.textAnimation`	`AnimatedNumberComponent`	Custom component used to render every animated number in the widget. Must accept `{ value, format?, className? }`. Defaults to a plain formatted span — drop in a flow / scramble / count renderer to animate.

Data & API

Prop	Type	Description
`apiUrl`	`string`	Override the Superbridge API base URL. Defaults to production.
`localDevelopmentApiKey`	`string`	Dev-only API key for use on `localhost`. See Local development.

Initial selection

Prop	Type	Description
`defaultFromChainUid` / `defaultFromChainId` / `defaultFromChainKey`	`string`	Initial source chain. Changes after initialization do not reset user selection.
`defaultToChainUid` / `defaultToChainId` / `defaultToChainKey`	`string`	Initial destination chain. Changes after initialization do not reset user selection.
`defaultFromTokenAddress`	`string`	Initial source token. Changes after initialization do not reset user selection.
`defaultToTokenAddress`	`string`	Initial destination token. Changes after initialization do not reset user selection.

Wallets

Prop	Type	Description
`openEvmWalletModal`	`() => void`	Open your own EVM wallet picker instead of the built-in modal. See Wallet management.
`openSvmWalletModal`	`() => void`	Open your own Solana wallet picker.
`openStarkWalletModal`	`() => void`	Open your own Starknet wallet picker.

Localization

Prop	Type	Description
`defaultLanguage`	`string`	Initial locale code (e.g. `'en'`, `'es'`). The widget owns language changes after initialization.

Behavior

Prop	Type	Description
`keyboardShortcuts`	`boolean`	Enable shortcuts like `f` to open the from-token selector. Default `false`.
`portalTarget`	`HTMLElement`	Render modals into this element instead of an internal portal. Must have (or live inside) the `.sb-widget` class so scoped styles apply.
`onEvent`	`(event: WidgetEvent) => void`	Subscribe to widget events for analytics, logging, or app-side reactions.