Avatars
Personalization of profiles is what makes identity great. This page covers the very special avatar record that enables users to take their avatar with them across the web.
Avatar
Avatars are an awesome way for users to express themselves. To get the user's avatar, all you need is their name. If you only have their address, see primary names. The following code snippets let you get the avatar for a user.
import { useEnsAvatar } from "wagmi";
function App() {
const { data: ensAvatar } = useEnsAvatar({
address: "luc.eth",
chainId: 1, // (1 = Ethereum Mainnet, 11155111 = Sepolia)
});
return (
<img
src={ensAvatar || "https://avatars.jakerunzer.com/luc.eth"}
alt="luc.eth"
/>
);
}
Try it outconst ensAvatar = await provider.getAvatar("luc.eth");
import { normalize } from "viem/ens";
import { publicClient } from "./client";
const ensAvatar = await publicClient.getEnsAvatar({
name: normalize("luc.eth"),
});
from ens.auto import ns
avatar = ns.get_text('alice.eth', 'avatar')
package main
import (
"fmt"
"github.com/ethereum/go-ethereum/ethclient"
ens "github.com/wealdtech/go-ens/v3"
)
func main() {
client, _ := ethclient.Dial("https://rpc.ankr.com/eth")
domain, _ := ens.Normalize("luc.eth")
resolver, _ := ens.NewResolver(client, domain)
avatar, _ := resolver.Text("avatar")
fmt.Println("Avatar: ", avatar)
}
The metadata service is run by ENS Labs. It is a free service web service that allows you to retrieve the avatar of an ENS name via a web request, as opposed to adding extra logic to your application and interacting with an ethereum node. This is of course centralised and should be used if absolutely necessary.
Avatar
An avatar record is simply a text record that has "avatar" as its key and a URI as its value, with some rules about what URI schemes are supported and how to process them. For more info, see ENSIP-11.
URI
Clients are expected to support a number of URI schemas, which aren't always web URIs, so the final result you see in your application will vary depending on how the library you are using has decided to handle avatar records.
http(s):- URI Scheme for HTTP(S) URLs. Libraries will most likely return the result directly.ipfs:- URI scheme for IPFS hashes. Libraries may decide to fetch the result from a public gateway for you.data:- URI Scheme for data URIs. Libraries will most likely return the result directly.eip155:- The URI scheme for EIP-155 identifiers for linking to NFTs on Ethereum based chains. A little complicated to resolve manually, most libraries should resolve this for you and return the underlying resource.
For EIP-155 NFT Avatars the nft must be owned by the wallet address the ENS
name resolves to. This is done by checking the ownerOf method on the NFT
contract.
URI
ethereum:- The URI scheme for Ethereum addressesbzz:- The URI scheme for Swarm hashes
Metadata
Avatars come in many different shapes and sizes. Not just the above URI schemas, but also in different file formats, sizes, and more. Although standards exist for some of these, files are not required to follow these standards.
Below is some information about the avatars your app might be loading.
| FileProperty: | Info/Recommendation |
|---|---|
| File Extension | Mostly png, jpeg, jpg, webp, gif, webm, but could be anything |
| File Size | We recommend having sensible timeouts |
| Aspect Ratio | We recommend object-fit: cover or setting a background color |
| Transparency | We recommend setting a background color as some images may contain transparency |
Luckily most browsers and network libraries have default timeouts to start with, we highly recommend that if you are doing any manual avatar downloading or fetching you add a sensible timeout.
