No Longer Reloading Pages on Network Change

Erik Marks
Nov 4 · 3 min read

This is one of the breaking changes we’re making on January 13, 2020. Click here for more details.

At long last, on January 13, 2020, MetaMask will no longer reload web pages when the selected network changes. This will be a breaking change for dapps that have yet to support EIP 1193-compatible providers. We expect this to enable UX improvements for all dapps that use MetaMask.

If you are a MetaMask user, you should not have to do anything. If, however, you interact with unmaintained legacy dapps, you will have to reload the dapp in the browser whenever you change networks in MetaMask. If you are a dapp developer, we encourage you to continue reading.

If you want to learn more about our reasoning for doing this, you can check out previous post on this topic, from 2018. Note that the example code in that article is outdated.

Summary

Inside MetaMask, the user can change the selected Ethereum network or change at any time. Currently, whenever the user changes the network, MetaMask asks the browser to reload the open pages of any connected dapps. On January 13, 2020, MetaMask will no longer ask the browser to do this. Instead, the dapp will have to listen for events emitted from the MetaMask inpage provider at window.ethereum.

Who is affected? What should you do instead?

If your dapp does not handle the network changing at any time after initialization, this will be a breaking change. To handle this, you need to listen for one of the events specified by EIP 1193, and handle the network change:

// you should use chainId for network identity, and listen for
// 'chainChanged'
ethereum.on('chainChanged', chainId => {
// handle the new network
})
// if you want to expose yourself to the problems associated
// with networkId, listen for 'networkChanged' instead
ethereum.on('networkChanged', networkId => {
// handle the new network
})
// if you want to do as little as possible, these three lines
// will emulate existing behavior
ethereum.on('chainChanged', () => {
document.location.reload()
})

To understand why you should only use chainId, check out this article by the inimitable Pedro Gomes. For the authoritative chainId and networkId list, check out chainId.network.

Why are we doing this?

Dapp developers have asked us to stop forcing reload for a very long time. By asking the browser to reload the page, we’re taking away the dapp’s power to manage its own UX. Worse, reloading the webpage is usually terrible UX. To get a complete account of our reasoning, check out Dan Finlay’s post on this from 2018 (but don’t follow any of the example code).

Conclusion

On January 13, 2020, MetaMask will finally stop reloading pages on network change. As a dapp developer, you should listen for the chainChanged event per EIP 1193. As a user, you should not have to do anything. We are excited to see the UX improvements that this will enable for the Ethereum ecosystem!

MetaMask

Erik Marks

Written by

Developer at MetaMask. Lagom in all things.

MetaMask

MetaMask

MetaMask is a bridge that allows you to visit the distributed web of tomorrow in your browser today. It allows you to run Ethereum dApps right in your browser without running a full Ethereum node.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade