Connection banner

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
Custom messages

No Ethereum network available

Props

Prop NameTypeIs RequiredDefault ValueDescription
currentNetworknumberoptional
null
requiredNetworknumberoptional
null
onWeb3Fallbackbooloptional
false
childrenshapeoptional
{
  notWeb3CapableBrowserMessage: null,
  noNetworkAvailableMessage: null,
  onWrongNetworkMessage: 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
Make sure your banner copy is clear and inspires action
Do
Switch to the Rinkeby network
Don't
The correct network was not detected
Avoid Web3 jargon
Technically, the functionality in this component tries to detect a Web3 provider. However, users don't need to know this.
Do
Switch browsers to use our blockchain features
Don't
No web3 detected
(ノ◕ヮ◕)ノ*:・゚✧

Are we missing anything?

If you have any extra insight you'd like to add, please raise an issue in Github.
Contribute