Design Guidelines
ENS is a tool to simplify the experience for your users by making blockchain addresses human-readable. Here are a series of guidelines and tools that will help you make good design choices and better implement ENS in your product.
In every instance where a user might otherwise see an Ethereum address, you can instead display an ENS name (with its avatar, if relevant). This is true for both read and write operations.
An example of read operations where it's appropriate to show an ENS name is the connected wallet status or representing an action from another user like a vote (Snapshot is a great example).
An example of write operations where it's appropriate to show an ENS name is when a user is inputting an address of any kind (token transfer, smart contract interaction, etc.).
Beyond these use cases, remember that the ENS Public Resolver allows you to link different kinds of resources to ENS names.
An ENS name should only be shown in place of an Ethereum address if the user has set a reverse record for their address, and if the reverse record matches the forward resolution. Learn more about primary names.
When replacing Ethereum addresses with ENS names you should consider these facts and best practices:
- Design a truncated version of the ENS name: ENS names can be very long; besides not being character-limited, users can create an infinite number of nested subdomains. If you do show a truncated version of the name, you should provide a way to view the full name, such as expanding it on hover.
- Not all ENS names end with .eth: ENS supports .eth and most DNS TLDs such as .com, .xyz, and 1200+ others. A correct implementation of ENS treats any dot-separated name as a potential ENS name and will attempt a look-up.
If you are showing the ENS name in its entirety or a truncated version, you should:
- Always provide the user a way to display the full Ethereum address: Notice how if you type "ens.eth" in the example above, the resolved ETH address appears under the name. This is especially important in high-risk situations, such as when the user is about to send a transaction or interact with a smart contract.
- Allow the user to copy the full Ethereum address: Allow the user to copy the full address either through a copy button or by selecting it.
- Optionally give the user a way to automatically open the Ethereum address in a block explorer such as Etherscan.
- Optionally show the balance amount of signed-in users. User research shows that users tend to recognise their own Ethereum address through their balance, as well as the address itself. This is meant only for the currently "signed in" user: only show their own balance and avoid showing the balance of other users.
Input fields where a user is supposed to insert Ethereum addresses should also accept and resolve ENS names. These inputs indicate that the user wants to interact with another user's Ethereum address or contract.
Follow these guidelines to create the best experience:
- Wait before resolving the ENS name: Debounce input fields that accept ENS names to avoid unnecessary network calls. You can also wait for the user to type a minimum of 1 character on both sides of the dot before resolving the name. For example, if the user type "ens.", there is no chance of it being a valid ENS name and therefore no need to resolve it. But after the user types "ens.e", it should be treated as a potential ENS name.
- Don't overwrite the input field with the Ethereum address: Show the resolved ENS name near the input field instead.
- Always display both the ENS name and the Ethereum address together : Do this after it has successfully been resolved.
You can offer free ENS names to your users which would not only improve their experience in your application, but also across the Ethereum ecosystem. See how to issue subdomains.
If your application needs to display many ENS Names in the UI, you can consider caching (for a short period of time) the ENS Name after it has been resolved or after the user has added the name in an input field.
Your optimistic UI can display the names from cache in non-risky situations, in which your user for example is simply browsing, but doesn't need to act or make decisions based on the information displayed. However, in all risky situations (eg transferring anything of value or interacting with a smart contract), you should perform a direct live resolution and get the most up to date information from the ENS Registry.
Also consider that users can change their information at any time which may not be tracked in the onchain registry, so you should periodically validate the information you cached. Learn more about offchain ENS names.
Even when ENS names are not available, research shows that there are some good practices to follow when displaying Ethereum addresses in dApps.
- Always show the initial ' 0x ' to indicate it's an address.
- When displaying the name in shorthand versions, show the first 5 and last 4 characters of the address. This is not a security requirement as vanity addresses can be spoofed relatively simply; this is a good practice because some users check the beginning of the name and others check the end of the name. Also, four is the highest number of elements that our mind can easily chunk, parse and remember well.
- Always provide a way to display the full Ethereum address.
Thorin is a react component library for the ENS design system. It provides a set of components that make it easier to follow the guidelines and best practices described above.
