Persistently displays a banner if:

• the user is not using a Web3-capable browser
• a Web3 provider can't be detected
• the current Ethereum network does not match the specified required network

The banner will help the user resolve the issue with device-specific language so they can use your dapp successfully.

Built with Rimble-UI

Installation

Install the package in your project directory with:

// with npm
npm install @rimble/connection-banner
// with yarn
yarn add @rimble/connection-banner

Usage Example

Default messages

Install the MetaMask browser extension to use our blockchain features in your current browser
Install MetaMask
<ConnectionBanner
  currentNetwork={3}
  requiredNetwork={1}
  onWeb3Fallback={true}
/>
<ConnectionBanner
  currentNetwork={3}
  requiredNetwork={1}
  onWeb3Fallback={true}
/>
Copy code

Custom messages

No Ethereum network available
<ConnectionBanner currentNetwork={4} requiredNetwork={1} onWeb3Fallback={true}>
  {{
    notWeb3CapableBrowserMessage: (
      <div>
        <p>Not a web3 capable browser</p>
      </div>
    ),
    noNetworkAvailableMessage: (
      <div>
        <p>No Ethereum network available</p>
      </div>
    ),
    onWrongNetworkMessage: (
      <div>
        <p>On wrong Ethereum network</p>
      </div>
    )
  }}
</ConnectionBanner>
<ConnectionBanner currentNetwork={4} requiredNetwork={1} onWeb3Fallback={true}>
  {{
    notWeb3CapableBrowserMessage: (
      <div>
        <p>Not a web3 capable browser</p>
      </div>
    ),
    noNetworkAvailableMessage: (
      <div>
        <p>No Ethereum network available</p>
      </div>
    ),
    onWrongNetworkMessage: (
      <div>
        <p>On wrong Ethereum network</p>
      </div>
    )
  }}
</ConnectionBanner>
Copy code

Props

{
  notWeb3CapableBrowserMessage: null,
  noNetworkAvailableMessage: null,
  onWrongNetworkMessage: null,
}

null

false

null

Default Messages

notWeb3CapableBrowserMessage - Desktop

Your browser doesn't support our blockchain features. Switch to either Brave, FireFox, Opera, or Chrome to continue

notWeb3CapableBrowserMessage - Mobile

Your browser doesn't support our blockchain features. Try a mobile wallet browser like Status, Coinbase wallet or Cipher

noNetworkAvailableMessage - Desktop only

Install the MetaMask browser extension to use our blockchain features in your current browser. installMetaMaskButton

onWrongNetworkMessage - Desktop

Switch to the requiredNetworkName Ethereum network in MetaMask. You're currently on currentNetworkName

onWrongNetworkMessage - Mobile

Switch to the requiredNetworkName Ethereum network in Settings. You're currently on currentNetworkName

Design guidelines

The connection banner helps users get on the right Ethereum network to use your dapp. It doesn't prevent them from interacting with your dapp's non-blockchain features. This is because we believe you should only ask the user to connect when they absolutely have to. That's why this component doesn't block the user, it just passively provides information they need should they want to do something on your dapp that will require a correct network.

Your content needs to instruct the user how to get to the right network, but a user can be at different levels of readiness.

1. On a network, but on the wrong one
2. Without a Web3 provider
3. On a browser that won't support a Web3 provider

That means you need different content that responds to the different situations described above. For example:

1. How to switch to the right network
2. How to get on a Web3 provider
3. Which browser to use instead

We've provided some messages in this component that should work for most dApps. However you may want to tweak them slightly to add a bit of your brand's personality. So here's some principles and tops you should keep in mind when editing the content.

Principles

• One thing at a time: if the user is using Safari, they're going to have to go through multiple steps to start using your dapp (changing browser and downloading MetaMask) however once they've done the first step (changed browser) there's another banner helping them to install MetaMask. This means you don't need to mention this in the wrong browser banner. Just keep your instruction clear and simple to follow and let the next banner explain the next step.
• Avoid connection: we've found that framing this action as "connecting" can cause confusion with connecting to the dapp. Plus, if you're using a Web3 provider, you'll automatically be on a network without having gone through the act of deliberately connecting. We like "Switch to" a different network as it reflects the simple process that it is.
• Keep it passive: it's not urgent that the user should follow your instructions just yet. So make it clear when they should bother changing network, e.g. to use your blockchain features
• Tell them where: because you aren't able to change network from a dapp, you should be as descriptive as you can in terms of where to change the network. This has its challenges as it can differ between products. "Settings" seems to be a safe term for Mobile, whereas you should use "MetaMask" on desktop.

Tips

Keep it active

Avoid Web3 jargon

Technically, the functionality in this component tries to detect a Web3 provider. However, users don't need to know this.