record.getAvatar
Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). Options, result, errors and examples for record.getAvatar.
Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12).
When to use
Use to show a profile picture for a name.
Details
http(s)anddata:URIs are returned as-is;ipfs://,ipns://,ar://and bare CIDs go throughgateways: the call's, else the client's (Ensforge.create({ gateways })), elsehttps://ipfs.ioandhttps://arweave.net(the client config also has a Swarm gateway,https://api.gateway.ethswarm.org, used forbzz://content hashes, not avatars).- NFT avatars (
eip155:1/erc721:…/…,erc1155) read the token's metadata and return its image. They resolve only on the client's own chain, and only when the name's ETH address owns the token (ENSIP-12):ownerOffor ERC-721, a non-zero balance for ERC-1155. - Returns
nullwhen the avatar is not set or cannot be loaded, unlessstrictis set.
Gotchas
- The public
ipfs.iogateway is rate limited (HTTP 429 under load): set your own gateway in production.
Signature
function getAvatar(client: Like, options: getAvatar.Options): Promise<getAvatar.ReturnType>Call it as ens.record.getAvatar(options) on a client, or Actions.record.getAvatar(client, options).
record.getAvatar.request(options) builds a deferred read for Actions.batch. See Look up many at once.
In React, use useAvatar.
Parameters
| Option | Type | Default | Description |
|---|---|---|---|
name (required) | string | ENS name to read. Normalized automatically. | |
gateways | Gateways | HTTP gateways for IPFS and Arweave content, overriding the client's gateways. | |
timeout | number | 10000 | Milliseconds to wait for NFT metadata. |
Also takes the read options.
Returns
Resolves to string | null. An http(s) or data: URL, or null.
Errors
| Error | Codes | When |
|---|---|---|
InvalidInputError | INVALID_NAME | the name cannot be normalized. |
NotFoundError | RECORD_NOT_FOUND, RESOLVER_NOT_FOUND | with strict. |
UnsupportedError | RESOLVER_PROFILE_UNSUPPORTED | with strict when the resolver supports none of the records. |
GatewayError | GATEWAY_REQUEST_FAILED, GATEWAY_RESPONSE_INVALID | with strict when NFT metadata cannot be loaded. |
DnsError | a DNS name's DNSSEC proof does not verify. | |
NetworkError | RPC_REQUEST_FAILED, RPC_TIMEOUT, RATE_LIMITED | the RPC request fails. |
It can also fail with the errors every read can (Errors.CommonError: ConfigError, ContractRevertError, InternalError, NetworkError).
See How errors work.
Examples
const src = await ens.record.getAvatar({ name: "nick.eth" })Example response
Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.
await ens.record.getAvatar({ name: "jesse.base.eth" })"https://zku9gdedgba48lmr.public.blob.vercel-storage.com/basenames/avatar/jesse.base.eth/1722020142962/cryptopunk-diuDROjlL5OLY6EcC5keHTsNAiWMSL.png"See also
record.getTextto read the raw avatar record
Was this page helpful?