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
`cssVariables`	`WidgetCssVariables`	CSS variable overrides for colors, fonts, radius, and per-shape tokens. See Theming.
`motion`	`MotionProps`	Per-element hover/tap/open transitions. See Theming.
`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.
`chains`	`ChainDto5[]`	Restrict the widget to a specific set of chains. Defaults to all chains enabled for your Rollie.

Defaults

Prop	Type	Description
`defaultFromChainUid` / `defaultFromChainKey`	`string`	Pre-select the source chain.
`defaultToChainUid` / `defaultToChainKey`	`string`	Pre-select the destination chain.
`defaultFromTokenAddress`	`string`	Pre-select the source token.
`defaultToTokenAddress`	`string`	Pre-select the destination token.

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.

Behavior

Prop	Type	Description
`language`	`string`	Locale code (e.g. `'en'`, `'es'`).
`onLanguageChange`	`(language: string) => void`	Called when the user switches language from inside the widget.
`urlSync`	`boolean`	Sync selected chains/tokens to URL query params. Default `true`.
`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.