@thirdweb-dev/react

thirdweb React SDK

Ultimate collection of React hooks for your web3 apps

Installation

The easiest way to get started with the React SDK is to use the CLI:

npx thirdweb create --app

Alternatively, you can install the SDK into your existing project using npm or yarn:

npm install @thirdweb-dev/react @thirdweb-dev/sdk ethers@5

yarn add @thirdweb-dev/react @thirdweb-dev/sdk ethers@5

Getting Started

Our SDK uses a Provider Pattern; meaning any component within the ThirdwebProvider will have access to the SDK. If you use the CLI to initialize your project, this is already set up for you.

Let's take a look at a typical setup:

Configure the ThirdwebProvider

Specify the network your smart contracts are deployed to in the desiredChainId prop and wrap your application like so:

import { ChainId, ThirdwebProvider } from "@thirdweb-dev/react";

const App = () => {
  return (
    <ThirdwebProvider desiredChainId={ChainId.Mainnet}>
      <YourApp />
    </ThirdwebProvider>
  );
};

Below are examples of where to set this up in your application:

Create React App • Next.js • Vite

Connect to a User's Wallet

Now the provider is set up, we can use all of the hooks and UI components available in the SDK, such as the ConnectWallet component.

Once the user has connected their wallet, all the calls we make to interact with contracts using the SDK will be on behalf of the user.

import { ConnectWallet, useAddress } from "@thirdweb-dev/react";

export const YourApp = () => {
  const address = useAddress();
  return (
    <div>
      <ConnectWallet />
    </div>
  );
};

The ConnectWallet component handles everything for us, including switching networks, accounts, displaying balances and more.

We can then get the connected address using the useAddress hook anywhere in the app.

Interact With Contracts

Connect to your smart contract using the useContract hook like so:

import { useContract } from "@thirdweb-dev/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");

  // Now you can use the contract in the rest of the component!
}

You can then use useContractRead and useContractWrite to read data and write transactions to the contract.

You pass the contract object returned from useContract to these hooks as the first parameter and the name of the function (or view/mapping, etc.) on your smart contract as the second parameter. If your function requires parameters, you can pass them as additional arguments.

For example, we can read the name of our contract like so:

import {
  useContract,
  useContractRead,
  useContractWrite,
} from "@thirdweb-dev/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: name, isLoading: loadingName } = useContractRead(
    contract,
    "name", // The name of the view/mapping/variable on your contract
  );
  const { mutate: setName, isLoading: settingName } = useContractWrite(
    contract,
    "setName", // The name of the function on your contract
  );
}

Using Extensions

Each extension you implement in your smart contract unlocks new functionality in the SDK.

These hooks make it easy to interact with your smart contracts by implementing the complex logic for you under the hood.

For example, if your smart contract implements ERC721Supply, you unlock the ability to view all NFTs on that contract using the SDK; which fetches all of your NFT metadata and the current owner of each NFT in parallel. In the React SDK, that is available using useNFTs:

import { useContract, useNFTs } from "@thirdweb-dev/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);
}

If we want to mint an NFT and our contract implements ERC721Mintable, we can use the useMintNFT hook to mint an NFT from the connected wallet; handling all of the logic of uploading and pinning the metadata to IPFS for us behind the scenes.

import { useContract, useNFTs, useMintNFT } from "@thirdweb-dev/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);
  const { mutate: mintNFT, isLoading: isMintingNFT } = useMintNFT(contract);
}

UI Components

The SDK provides many UI components to help you build your application.

For example, we can render each of the NFTs using the NFT Media Renderer component, making use of the loading state from useNFTs:

import { useContract, useNFTs, ThirdwebNftMedia } from "@thirdweb-dev/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);

  return (
    <div>
      <h2>My NFTs</h2>
      {isReadingNfts ? (
        <p>Loading...</p>
      ) : (
        <div>
          {nfts.map((nft) => (
            <ThirdwebNftMedia
              key={nft.metadata.id}
              metadata={nft.metadata}
              height={200}
            />
          ))}
        </div>
      )}
    </div>
  );
}

The Web3Button component ensures the user has connected their wallet and is currently configured to the same network as your smart contract before calling the function. It also has access to the contract directly, allowing you to perform any action on your smart contract when the button is clicked.

For example, we can mint an NFT like so:

import {
  useContract,
  useNFTs,
  ThirdwebNftMedia,
  Web3Button,
} from "@thirdweb-dev/react";

const contractAddress = "<CONTRACT_ADDRESS>";
export default function Home() {
  const { contract } = useContract(contractAddress);
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);

  return (
    <div>
      {/* ... Existing Display Logic here ... */}

      <Web3Button
        contractAddress={contractAddress}
        action={(contract) =>
          contract.erc721.mint({
            name: "Hello world!",
            image:
              // You can use a file or URL here!
              "ipfs://QmZbovNXznTHpYn2oqgCFQYP4ZCpKDquenv5rFCX8irseo/0.png",
          })
        }
      >
        Mint NFT
      </Web3Button>
    </div>
  );
}

Advanced Configuration

The ThirdwebProvider offers a number of configuration options to control the behavior of the React and Typescript SDK.

These are all the configuration options of the <ThirdwebProvider />. We provide defaults for all of these, but you customize them to suit your needs.

import { ChainId, IpfsStorage, ThirdwebProvider } from "@thirdweb-dev/react";

const KitchenSinkExample = () => {
  return (
    <ThirdwebProvider
      desiredChainId={ChainId.Mainnet}
      chainRpc={{ [ChainId.Mainnet]: "https://mainnet.infura.io/v3" }}
      dAppMeta={{
        name: "Example App",
        description: "This is an example app",
        isDarkMode: false,
        logoUrl: "https://example.com/logo.png",
        url: "https://example.com",
      }}
      storageInterface={new IpfsStorage("https://your.ipfs.host.com")}
      supportedChains={[ChainId.Mainnet]}
      walletConnectors={[
        "walletConnect",
        { name: "injected", options: { shimDisconnect: false } },
        {
          name: "walletLink",
          options: {
            appName: "Example App",
          },
        },
        {
          name: "magic",
          options: {
            apiKey: "your-magic-api-key",
            rpcUrls: {
              [ChainId.Mainnet]: "https://mainnet.infura.io/v3",
            },
          },
        },
      ]}
      sdkOptions={{
        gasSettings: { maxPriceInGwei: 500, speed: "fast" },
        readonlySettings: {
          chainId: ChainId.Mainnet,
          rpcUrl: "https://mainnet.infura.io/v3",
        },
        gasless: {
          openzeppelin: {
            relayerUrl: "your-relayer-url",
          },
        },
      }}
    >
      <YourApp />
    </ThirdwebProvider>
  );
};

Available hooks

Main hooks

Hook	Description
useSDK	Access the instance of the thirdweb SDK created by the ThirdwebProvider.
useContract	Use this resolve a contract address to a smart contract instance.
useContractWrite	Use this to get data from a contract read-function call.
useContractRead	Use this to get a function to make a write call to your contract.
useContractEvents	Use this to get the contract metadata for a (built-in or custom) contract.
useContractMetadata	Use this to get the contract metadata for a (built-in or custom) contract.

Wallet connection

Hook	Description
useAddress	Hook for accessing the address of the connected wallet.
useMetamask	Hook for connecting to a Metamask wallet.
useWalletConnect	Hook for connecting to a mobile wallet with Wallet Connect.
useCoinbaseWallet	Hook for connecting to a Coinbase wallet.
useMagic	Hook for connecting to an email wallet using magic link.
useGnosis	Hook for connecting to a Gnosis Safe.
useDisconnect	Hook for disconnecting the currently connected wallet.

Network connection

Hook	Description
useChainId	Hook for accessing the chain ID of the network the current wallet is connected to
useNetwork	Hook for getting metadata about the network the current wallet is connected to and switching networks.
useNetworkMismatch	Hook for checking whether the connected wallet is on the correct network specified by the desiredChainId passed to the .

NFT

Hook	Description
useNFT	Use this to get an individual NFT token of your NFTContract.
useNFTs	Use this to get a list of NFT tokens of your NFTContract.
useTotalCirculatingSupply	Use this to get a the total (minted) supply of your NFTContract.
useOwnedNFTs	Use this to get a the owned NFTs for a specific Erc721OrErc1155 and wallet address.
useNFTBalance	Use this to get a the total balance of a NFTContract and wallet address.
useTotalCount	Use this to get the total count of NFT tokens of your NFTContract.
useMintNFT	Use this to mint a new NFT on your Erc721OrErc1155.
useMintNFTSupply	Use this mint extra supply on your Erc1155.
useTransferNFT	Use this to transfer tokens on your NFTContract.
useAirdropNFT	Use this to airdrop tokens on your Erc1155.
useBurnNFT	Use this to burn an NFT on your Erc721OrErc1155.

Token

Hook	Description
useTokenSupply	Use this to get a the total supply of your contract.
useTokenBalance	Use this to get the balance of your contract for a given address.
useTokenDecimals	Use this to get the decimals of your contract for a given address.
useMintToken	Use this to mint new tokens on your contract.
useClaimToken	Use this to claim tokens from your contract.
useTransferToken	Use this to transfer tokens on your contract.
useTransferBatchToken	Use this to transfer batch tokens on your contract.
useBurnToken	Use this to burn tokens on your contract.

Marketplace

Hook	Description
useListing	Use this to get a specific listing from the marketplace.
useListings	Use this to get a list all listings from your marketplace contract.
useListingsCount	Use this to get a count of all listings on your marketplace contract.
useActiveListings	Use this to get a list active listings from your marketplace contract.
useWinningBid	Use this to get a the winning bid for an auction listing from your marketplace contract.
useAuctionWinner	Use this to get the winner of an auction listing from your marketplace contract.
useBidBuffer	Use this to get the buffer in basis points between offers from your marketplace contract.
useCreateDirectListing	Use this to create a new Direct Listing on your marketplace contract.
useCreateAuctionListing	Use this to create a new Auction Listing on your marketplace contract.
useCancelListing	Use this to cancel a listing on your marketplace contract.
useMakeBid	Use this to place a bid on an auction listing from your marketplace contract.
useBuyNow	Use this to buy out an auction listing from your marketplace contract.
useBuyDirectListing	Use this to buy from a direct listing in your marketplace v3 contract.

Permissions Controls

Hook	Description
useAllRoleMembers	Use this to get the roles of all members.
useRoleMembers	Use this to get the members of a role.
useIsAddressRole	Use this to check if a WalletAddress is a member of a role.
useSetAllRoleMembers	Use this to OVERWRITE the list of addresses that are members of specific roles.
useGrantRole	Use this to grant a WalletAddress a specific role.
useRevokeRole	Use this to revoke a WalletAddress a specific role.

Drop

Hook	Description
useUnclaimedNFTs	Use this to get a list of unclaimed NFT tokens of your ERC721 Drop contract.
useClaimedNFTs	Use this to get a list of claimed (minted) NFT tokens of your ERC721 Drop contract..
useUnclaimedNFTSupply	Use this to get the total unclaimed NFT supply of your ERC721 Drop contract.
useClaimedNFTSupply	Use this to get the total claimed (minted) NFT supply of your ERC721 Drop contract.
useBatchesToReveal	Use this to get a list of batches that are ready to be revealed.
useClaimNFT	Use this to claim a NFT on your DropContract
useLazyMint	Use this to lazy mint a batch of NFTs on your DropContract.
useDelayedRevealLazyMint	Use this to lazy mint a batch of delayed reveal NFTs on your DropContract.
useRevealLazyMint	Use this to reveal a batch of delayed reveal NFTs on your RevealableContract.

Claim Conditions

Hook	Description
useActiveClaimCondition	Use this to get the active claim condition for ERC20, ERC721 or ERC1155 based contracts.
useClaimConditions	Use this to get all claim conditions for ERC20, ERC721 or ERC1155 based contracts.
useClaimIneligibilityReasons	Use this to check for reasons that prevent claiming for either ERC20, ERC721 or ERC1155 based contracts.
useSetClaimConditions	Use this to set claim conditions on your DropContract.
useResetClaimConditions	Use this to reset claim conditions on your DropContract.