Customization Guide

Native allows for a full customization for the swap widget such as theme customization, external wallet provider, and many more.

You can visit widget.native.org for a live demo and playground.

Wallet Setting & Custom Provider

The Native swap widget allows developers to utilize their existing Dapp connections by passing the walletSettings prop. The provider passed is used by the widget to enable users to connect their wallets, fetch balances, and submit transactions through the user's connected wallet.

If your app does not maintain its own web3 provider, you can omit the walletSettings prop. The widget will utilize built-in wallet connection functionality (using the rainbowkit library), making it easy for you to integrate web3 into your app!

If you already have a web3 provider, you can pass your walletSettings, which includes several pieces of information such as the address, chainId, connect function, and providerobject, directly into the provider prop. Both ethers and web3.js provider objects are compatible with the widget provider, as well as any EIP-1193 provider. You can directly use the providers returned from web3-react or wagmi (both are ethers providers). If the user's wallet is not connected, the widget will prompt them to "Connect wallet" using the connect function.

Example of the custom wallet setting and providers:

import SwapWidget from '@native_org/widgets';

const App = () => {
  return (
    <SwapWidget
      apiKey={apiKey}
      baseApiUrl={apiUrl}
      walletSettings={{
        usingNative: false,
        address: walletAddress,
        chainId,
        connect,
        provider,
      }}
    />
  )
}

Theme Customization

You can customize the colors, font, and background of the swap widget to match the look and feel of your dApp. You can also toggle between light and dark modes. This section explains how to customize each attribute of the widget with your own theme.

Generally, the Native swap widget supports theme customization via the theme prop, which allows for setting the bg color and text color. The Native swap widget also provides a basic preset to support both light and dark themes.

Example of theme customization can be seen in the following:

const App = () => {
  return (
    <SwapWidget
      apiKey={apiKey}
      baseApiUrl={apiUrl}
      theme={{
        theme: 'light'
      }}
    />
  )
}

const App = () => {
  return (
    <SwapWidget
      apiKey={apiKey}
      baseApiUrl={apiUrl}
      theme={{
        theme: 'dark'
      }}
    />
  )
}

const App = () => {
  return (
    <SwapWidget
      apiKey={apiKey}
      baseApiUrl={apiUrl}
      theme={{
        theme: 'dark',
        bg: {
          page: '#111423',
          primary: '#111423',
          secondary: '#23273A',
          cta: '#FFEE05',
        },
        text: {
          primary: '#ffffff',
          secondary: '#9CA3AF',
          border: '#50515a',
          borderLight: '#50515a',
          cta: '#FFEE05',
        },
      }}
    />
  )
}

Furthermore, to support our KOL and community, we provide a basic profile template to make Widget unique to them

const App = () => {
  return (
    <SwapWidget
      apiKey={apiKey}
      baseApiUrl={apiUrl}
      theme={{
        theme: 'light',
        profile: {
          enabled: true,
          coverImage: 'https://static.native.org/degen-sparta-cover.jpg',
          profileImage: 'https://static.native.org/degen-sparta-pfp.jpg',
          name: '@DegenSpartan',
          nameUrl: 'https://twitter.com/DegenSpartan',
          desc: '',
        },
      }}
    />
  )
}

Custom Styling

If the custom theme does not meet your needs and you want further customization, you can pass custom CSS styling through the containerStyle prop, which directly targets the native component. Each component has its own CSS class. Our custom styling is extended from the styled component library, which supports more advanced CSS selectors such as pseudo classes, pseudo elements, media queries, etc.

Example of custom styling prop

const App = () => {
  return (
    <SwapWidget
      apiKey={apiKey}
      baseApiUrl={apiUrl}
      theme={{
        theme: 'dark',
        bg: {
          page: '#111423',
          primary: '#111423',
          secondary: '#23273A',
          cta: '#FFEE05',
        },
        text: {
          primary: '#ffffff',
          secondary: '#9CA3AF',
          border: '#50515a',
          borderLight: '#50515a',
          cta: '#FFEE05',
        },
      }}
      containerStyle={{
        '.native-bt-contained': {
          color: '#111423',
        },
        '.native-bt-contained:disabled': {
          color: '#9CA3AF',
        },
        '.native-bt-contained.native-max-button': {
          color: '#ffffff',
        },
      }}
    />
  )
}

Chain Configuration

By default, the Native swap widget supports both the mainnet and testnet, including Ethereum mainnet, sepolia testnet, BNB mainnet, BNB testnet, Polygon mainnet, and Mumbai testnet.

You can disable some networks and even customize the initial input and output tokens. Note that once you pass the chainSettings prop, the default supported network is no longer applied. You need to manually choose which networks you support via the isSupported field.

Example of chain configuration

const App = () => {
  return (
    <SwapWidget
      apiKey={apiKey}
      baseApiUrl={apiUrl}
      chainSettings={{
        56: {
          isSupported: true,
          initialInputToken: {
            address: '0x55d398326f99059fF775485246999027B3197955',
          },
          initialOutputToken: {
            address: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d',
          },
        },
        1: {
          isSupported: true,
          initialInputToken: {
            address: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
          },
          initialOutputToken: {
            address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
          },
        },
      }}
    />
  )