![License](https://badgen.net/github/license/spectrexyz/use-nft)
useNft() allows to access the metadata of any NFT (EIP 721, EIP 1155 and more) on the Ethereum blockchain.
Install
npm install --save use-nft
Usage
useNft() uses a concept of “fetchers”, in order to provide different ways to retrieve data from Ethereum. If you use the Ethers in your app, using ethersFetcher()
is recommended. Otherwise you can use ethereumFetcher()
, which only requires a standard Ethereum provider, like the one provided by MetaMask.
import { getDefaultProvider, } from "ethers"
import { NftProvider, useNft } from "use-nft"
const ethersConfig = {
provider: getDefaultProvider("homestead"),
}
function App() {
return (
<NftProvider fetcher={["ethers", ethersConfig]}>
<Nft />
</NftProvider>
)
}
function Nft() {
const { loading, error, nft } = useNft(
"0xd07dc4262bcdbf85190c01c996b4c06a461d2430",
"90473"
)
if (loading) return <>Loading…</>
if (error || !nft) return <>Error.</>
return (
<section>
<h1>{nft.name}</h1>
<img src={nft.image} alt="" />
<p>{nft.description}</p>
<p>Owner: {nft.owner}</p>
<p>Metadata URL: {nft.metadataUrl}</p>
</section>
)
}
API
useNft(contract, tokenId)
The useNft() hook requires two arguments: the NFT contract
address, and its token ID.
The returned value is an object containing information about the loading state:
const { status, loading, error, reload, nft } = useNft(
"0xd07dc4262bcdbf85190c01c996b4c06a461d2430",
"90473"
)
status
loading
error
reload
nft
nft.name
nft.description
nft.image
nft.imageType
nft.owner
nft.metadataUrl
nft.rawData
As TypeScript type:
type NftResult = {
status: "error" | "loading" | "done"
loading: boolean
reload: () => void
error?: Error
nft?: {
description: string
image: string
imageType: "image" | "video" | "unknown"
name: string
owner: string
metadataUrl?: string
rawData: Record<string, unknown> | null
}
}
<NftProvider />
NftProvider requires a prop to be passed: fetcher
. It can take a declaration for the embedded fetchers, or you can alternatively pass a custom fetcher.
fetcher
With Ethers.js
Make sure to add either ethers
or @ethersproject/contracts
to your app:
npm install --save ethers
Then:
<NftProvider fetcher={["ethers", { provider }]} />
Where provider
is a provider from the Ethers library (not to be mistaken with standard Ethereum providers).
With an Ethereum provider
<NftProvider fetcher={["ethereum", { ethereum }]} />
Where ethereum
is a standard Ethereum provider.
Custom fetcher
A fetcher is an object implementing the Fetcher
type:
type Fetcher<Config> = {
config: Config
fetchNft: (contractAddress: string, tokenId: string) => Promise<NftMetadata>
}
type NftMetadata = {
name: string
description: string
image: string
}
See the implementation of the Ethers and Ethereum fetchers for more details.
ipfsUrl
A function that allows to define the IPFS gateway (defaults to https://ipfs.io/
).
Default value:
function ipfsUrl(cid, path = "") {
return `https://ipfs.io/ipfs/${cid}${path}`
}
imageProxy
Allows to proxy the image URL. This is useful to optimize (compress / resize) the raw NFT images by passing the URL to a service.
Default value:
function imageProxy(url, metadata) {
return url
}
jsonProxy
Allows to proxy the JSON URL. This is useful to get around the CORS limitations of certain NFT services.
Default value:
function jsonProxy(url) {
return url
}
FetchWrapper
FetchWrapper
is a class that allows to use the library with other frontend libraries than React, or with NodeJS. Unlike the useNft()
hook, FetchWrapper#fetchNft()
does not retry, cache, or do anything else than attempting to fetch the NFT data once.
import { FetchWrapper } from "use-nft"
Pass the fetcher declaration to the FetchWrapper
and call the fetchNft
function to retreive the NFT data.
const fetcher = ["ethers", { provider: ethers.getDefaultProvider() }]
const fetchWrapper = new FetchWrapper(fetcher)
const result = await fetchWrapper.fetchNft(
"0xd07dc4262bcdbf85190c01c996b4c06a461d2430",
"90473"
)
The fetchNft()
function returns a promise which resolves to an NftMetadata
object.
Supported NFT formats
Any standard NFT (EIP 721 or EIP 1155) is, in theory supported by useNft(). In practice, some adjustments are needed to support some NFT formats, either because their implementation doesn’t follow the specification or because some parts of the specifications can be interpreted in different ways.
This table keeps track of the NFT minting services that have been tested with useNft() and the adaptations needed.
License
MIT
Special Thanks 🙏
Thanks to ImageKit.io for supporting the project by providing a free plan.