Widget

Implement the Synapse Bridge into your dApp frontend

The Synapse Widget is a trivial implementation of the current Synapse bridge that enables protocols to integrate the bridge into their Frontend with little to no Engineering resources.

This explains how to integrate the bridge widget into your dApp in just a few minutes. This widget enables users to bridge tokens directly on your site, utilizing the Synapse Protocol. Example use cases include:

Building a custom frontend for the Synapse Protocol
Bridging assets in a DeFi application
Acquiring a token to participate in a web3 game

This guide shows how to customize the widget to seamlessly blend with your app's theme by altering colors, fonts, and the token list. Learn to make the widget appear as an integral part of your application.

Implementation

The widget is available on npm or yarn.

npm:

npm install @synapsecns/widget

yarn:

yarn add @synapsecns/widget

Get Started

To get started, import the Widget React component into your App. You will need a web3Provider parameter to pass to the widget. The demo landing page app, for example, defines this provider from the ethers library. However, the component supports any similar provider:

import { Bridge } from '@synapsecns/widget'

const MyApp = () => {
  const web3Provider = new ethers.BrowserProvider(window.ethereum)

  return <Bridge web3Provider={web3Provider} />
}

Your site should now display a fully operational bridge widget integrating the routes and tokens supported by the Synapse protocol. By utilizing Synapse's multiple routers, you will be able to find the best quotes to support your bridging use case.

The widget accepts a number of props to customize its functionality and appearance. Below is a quick summary with more detailed explanations later on.

web3Provider Web3Provider. Required.

customRpcs Custom JSON-RPC endpoints for your consumer application. Optional but recommended.

customTheme Custom theme for the widget. Optional. If not provided, defaults to light theme.

container HTML element to render the widget in. Optional. If not provided, false.

targetChainIds List of chain IDs for the destination side of your consumer app. Optional. If not provided, defaults to all Synapse Protocol supported networks.

targetTokens List of tokens to display in the widget. These tokens are imported from the widget package. Optional. If not provided, defaults to all Synapse Protocol supported tokens.

protocolName A short name for users of the widget to identify the protocol. Optional. If not provided, defaults to 'Target'.

hideConsoleErrors Boolean to enable suppressing Synapse (SDK, Widget) console.error messages in your consumer app's browser. If not provided, defaults to logging error messages.

A list of targetTokens can be found here
A list of Synapse Protocol supported chains can be found here

web3Provider prop (required)

ethers v6

const web3Provider = new ethers.BrowserProvider(window.ethereum)

ethers v5

const web3Provider = new ethers.providers.Web3Provider(window.ethereum, 'any')

Enhanced and Reliable Performance

The bridge widget is a React component designed for straightforward integration into any React-based project. Engineered for immediate functionality, and apart from a web3Provider, it requires no initial parameters or web3 setup to begin operation. The widget facilitates bridging across all networks where the Synapse Protocol is active.

While the widget is primed for immediate use without configuration as it provides some basic primary and fallback JSON-RPC endpoints, we encourage developers to specify their own for enhanced performance. This can be done by including a customRpcs parameter in the format of an object with chain ids as keys and their associated RPC endpoints as values.

import { Bridge, CustomRpcs } from '@synapsecns/widget'

const customRpcs: CustomRpcs = {
  1: 'https://ethereum.my-custom-rpc.com',
  10: 'https://optimism.my-custom-rpc.com',
  42161: 'https://arbitrum.my-custom-rpc.com',
}

const MyApp = () => {
  const web3Provider = new ethers.BrowserProvider(window.ethereum)

  return <Bridge web3Provider={web3Provider} customRpcs={customRpcs} />
}

Token and Chain Customization

To further tailor the bridge widget to meet the specific demands of your project, additional optional targetTokens and targetChainIds parameters are provided. These allow for customizing which chain and tokens your consuming application will support bridging to. This is effectively a way to filter for specific tokens on destination chain your application's users bridge.

import { Bridge, CustomRpcs, ETH, USDC, USDT } from '@synapsecns/widget'

const MyApp = () => {
  const web3Provider = new ethers.BrowserProvider(window.ethereum)

  return (
    <Bridge
      web3Provider={web3Provider}
      targetTokens={[ETH, USDC, USDT]}
      targetChainIds={[42161, 43114]}
    />
  )
}

Note: Token naming convention is based on the tokens provided by @synapsecns/widget. For example, USDC on Metis is METISUSDC instead of simply USDC. The package's src/constants/bridgeable.ts file contains a detailed list of supported tokens and the chains they live on. Additionally, to see a detailed list of Synapse Protocol supported chains, please see src/constants/chains.ts.

useBridgeSelections Hook

The widget also provides a useBridgeSelections hook that can be used to access the selected tokens and chains. This hook returns an object of type BridgeSelections which has fields of originChain, originToken, destinationChain, and destinationToken.

originChain and destinationChain structure:

{
  id,
  name,
}

originToken and destinationToken structure:

{
  symbol,
  address
}

In the consumer app:

const { originChain, originToken, destinationChain, destinationToken } =
  useBridgeSelections()

Theme Customization

The widget is designed to be easily customized to match your app's theme. The widget accepts an optional customTheme configurable bgColor parameter for 'dark', 'light', and custom color modes:

<Bridge web3Provider={web3Provider} customTheme={{ bgColor: 'light' }} />

Additionally, the widget supports more complex custom themes with the customTheme property. This allows for more fine-grained control over the widget's colors and fonts.

const customTheme = {
  // Generate from base color, 'dark', or 'light'
  bgColor: '#08153a',

  // Basic customization
  '--synapse-text': 'white',
  '--synapse-secondary': '#ffffffb3',
  '--synapse-root': '#16182e',
  '--synapse-surface': 'linear-gradient(90deg, #1e223de6, #262b47e6)',
  '--synapse-border': 'transparent',

  // Full customization (Uses based colors by default)
  '--synapse-focus': 'var(--synapse-secondary)',
  '--synapse-select-bg': 'var(--synapse-root)',
  '--synapse-select-text': 'var(--synapse-text)',
  '--synapse-select-border': 'var(--synapse-border)',
  '--synapse-button-bg': 'var(--synapse-surface)',
  '--synapse-button-text': 'var(--synapse-text)',
  '--synapse-button-border': 'var(--synapse-border)',

  // Transaction progress colors (set bgColor to auto-generate)
  '--synapse-progress': 'hsl(265deg 100% 65%)',
  '--synapse-progress-flash': 'hsl(215deg 100% 65%)',
  '--synapse-progress-success': 'hsl(120deg 100% 30%)',
  '--synapse-progress-error': 'hsl(15deg 100% 65%)',
}

<Bridge
  web3Provider={web3Provider}
  customTheme={customTheme}
/>

Please see the examples/landing-page folder for more examples.

Container Customization

The widget additionally supports a container property of true or false to adjust its width to the container it's in.

<Bridge web3Provider={web3Provider} container={true} />

Example Apps

Within the repository's /examples folder, there are three example apps. The landing-page folder contains a fully functional demo with customizations of the widget. The with-react and with-next folders contain a simple implementation of the widget using React and Next.js, respectively.

If you have any questions or need help implementing the widget, feel free to reach out to the team in Discord!

PreviousExample NextREST API

Last updated 1 month ago