Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/VGLoic/metamask-react
A simple Context provider and consumer hook in order to provide a simple API for interacting with MetaMask in the browser
https://github.com/VGLoic/metamask-react
Last synced: 3 months ago
JSON representation
A simple Context provider and consumer hook in order to provide a simple API for interacting with MetaMask in the browser
- Host: GitHub
- URL: https://github.com/VGLoic/metamask-react
- Owner: VGLoic
- License: mit
- Created: 2021-01-13T10:50:39.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-08-20T11:25:38.000Z (over 1 year ago)
- Last Synced: 2024-04-14T10:51:35.520Z (8 months ago)
- Language: TypeScript
- Size: 1.07 MB
- Stars: 137
- Watchers: 5
- Forks: 25
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# MetaMask React
[](https://coveralls.io/github/VGLoic/metamask-react?branch=main)
Simplistic Context provider and consumer hook in order to manage MetaMask in the browser.
## Installation
The recommended way to use MetaMask React with a React app is to install it as a dependency.
If you use `npm`:
```console
npm install metamask-react
```
Or if you use `yarn`:
```console
yarn add metamask-react
```
## Quick Start
The first step is to wrap your `App` or any React subtree with the `MetaMaskProvider`
```TypeScript
// index.js
import { MetaMaskProvider } from "metamask-react";
...
ReactDOM.render(
,
document.getElementById('root')
);
```
In any React child of the provider, one can use the `useMetaMask` hook in order to access the state and methods.
```TypeScript
// app.js
import { useMetaMask } from "metamask-react";
...
function App() {
const { status, connect, account, chainId, ethereum } = useMetaMask();
if (status === "initializing") return
Synchronisation with MetaMask ongoing...
if (status === "unavailable") return
MetaMask not available :(
if (status === "notConnected") return Connect to MetaMask
if (status === "connecting") return
Connecting...
if (status === "connected") return
Connected account {account} on chain ID {chainId}
return null;
}
```
## Statuses and behavior
The `MetaMaskProvider` will first initialise the state with `initializing` status, the `account` and `chainId` will be `null`. A synchronization is performed in order to derive the MetaMask state.
If the `ethereum` object is not present or if it is not the one associated to MetaMask, the synchronisation will change the status to `unavailable`.
Otherwise, a check is performed in order to detect if MetaMask has already connected accounts for the application.
In case of no connected accounts, the status will be `notConnected`, otherwise the status will be `connected`.
Here is an abstract on the different statuses:
- `initializing`: the provider is currently initializing by synchronizing with MetaMask
- `unavailable`: MetaMask is not available, nothing will be done
- `notConnected`: MetaMask is available but not connected to the application
- `connected`: MetaMask is connected to the application
- `connecting`: the connection of your accounts to the application is ongoing
## Chain utils
The context exposes two methods in order to facilitate the management of the networks. These methods are wrappers around the JSON RPC requests handled by MetaMask, see [MetaMask documentation](https://docs.metamask.io/guide/rpc-api.html#table-of-contents) for additional information.
The first one is to request a switch to a different network
```TypeScript
function WrongNetwork() {
const { switchChain } = useMetaMask();
// Request a switch to Ethereum Mainnet
return (
switchChain("0x1")}>Switch to Ethereum Mainnet
)
}
```
The second one is a request to add to MetaMask a network and then connect to it
```TypeScript
function WrongNetwork() {
const { addChain } = useMetaMask();
const gnosisChainNetworkParams = {
chainId: "0x64",
chainName: "Gnosis",
nativeCurrency: {
name: "xDai",
symbol: "XDAI",
decimals: 18,
},
rpcUrls: ["https://rpc.gnosischain.com/"],
blockExplorerUrls: ["https://gnosisscan.io/"],
};
// Request to add Gnosis chain and then switch to it
return (
addChain(gnosisChainNetworkParams)}>Add Gnosis chain
)
}
```
Finally, here is a non exhaustive list of the networks and their chain IDs
```TypeScript
const networks = {
mainnet: "0x1", // 1
// Test nets
goerli: "0x5", // 5
ropsten: "0x3", // 3
rinkeby: "0x4", // 4
kovan: "0x2a", // 42
mumbai: "0x13881", // 80001
// Layers 2
arbitrum: "0xa4b1", // 42161
optimism: "0xa", // 10
// Side chains
polygon: "0x89", // 137
gnosisChain: "0x64", // 100
// Alt layer 1
binanceSmartChain: "0x38", // 56
avalanche: "0xa86a", // 43114
cronos: "0x19", // 25
fantom: "0xfa" // 250
}
```
## Type safe hook
Most of the time, the application will use the state when the user is connected, i.e. with status `connected`. Therefore the hook `useConnectedMetaMask` is additionally exposed, it is the same hook as `useMetaMask` but is typed with the connected state, e.g. the `account` or the `chainId` are necessarily not `null`. This hook is only usable when the status is equal to `connected`, it will throw otherwise.
```TypeScript
function MyComponent() {
const {
// typed as string - can not be null
account,
// typed as string - can not be null
chainId
} = useConnectedMetaMask();
return
Connected account {account} on chain ID {chainId}
}
```
## Contributing :rocket:
Contributions are welcome! Please follow the guidelines in the [contributing document](/CONTRIBUTING.md).