onchain-uiToken logo
Display a token image with a symbol, name, or address fallback when no image loads.
TokenLogo shows a token image from src or looks one up using chainId and address. If no image loads, it shows fallback text.
token-logo.tsxShow code
import { TokenLogo } from "@/components/ui/token-logo"export function TokenLogoDemo() { return ( <TokenLogo src="https://assets.coingecko.com/coins/images/279/large/ethereum.png" symbol="ETH" name="Ethereum" /> )}Installation
npx shadcn add @onchain-ui/token-logoRequirements
This component uses the shadcn tooltip. The install adds components/ui/tooltip.tsx if it is missing, or uses your existing file. Wrap your app with TooltipProvider to enable tooltips.
Usage
import { TokenLogo } from "@/components/ui/token-logo"
<TokenLogo
src="https://assets.coingecko.com/coins/images/279/large/ethereum.png"
symbol="ETH"
name="Ethereum"
/>TokenLogo uses a plain img element for portability. It does not require Next.js image configuration and works with arbitrary token image URLs from APIs, indexers, and token lists.
Set isNative to show the chain's native currency icon. Use this for ETH even if your metadata includes a wrapped-token address.
See Icon resolution for the lookup order and fallback rules.
Examples
Automatic icons
Without a src, TokenLogo asks the crypto-icons adapter to find an icon using chainId and address. The default adapter builds a URL for the Trust Wallet assets repository. If the image fails to load, the component shows fallback text.
token-logo-inferred.tsxShow code
import { TokenLogo } from "@/components/ui/token-logo"export function TokenLogoInferred() { return ( <TokenLogo chainId={8453} address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" symbol="USDC" name="USD Coin" /> )}For production apps, pass src from your token metadata or edit lib/onchain/crypto-icons.tsx to use your own token list or CDN.
Fallback
If the selected image fails to load or no icon is available, the component shows fallback. Without a custom fallback, it uses text from the token symbol, name, or address, then ?.
token-logo-fallback.tsxShow code
import { TokenLogo } from "@/components/ui/token-logo"export function TokenLogoFallback() { return <TokenLogo symbol="USDC" name="USD Coin" />}Sizes
Set size to xs, sm, md, lg, or xl.
token-logo-sizes.tsxShow code
import { TokenLogo } from "@/components/ui/token-logo"export function TokenLogoSizes() { return ( <div className="flex items-center gap-3"> <TokenLogo symbol="ETH" size="xs" /> <TokenLogo symbol="ETH" size="sm" /> <TokenLogo symbol="ETH" size="md" /> <TokenLogo symbol="ETH" size="lg" /> <TokenLogo symbol="ETH" size="xl" /> </div> )}Custom fallback
Pass fallback to replace the default text. Use fallbackClassName to style it.
token-logo-custom-fallback.tsxShow code
import { TokenLogo } from "@/components/ui/token-logo"export function TokenLogoCustomFallback() { return ( <TokenLogo symbol="WETH" fallback="Ξ" className="border-blue-500/30 bg-blue-500/10 text-blue-600 dark:text-blue-300" /> )}Tooltip
Enable an animated tooltip when the logo appears without nearby token text.
token-logo-tooltip.tsxShow code
import { TokenLogo } from "@/components/ui/token-logo"export function TokenLogoTooltip() { return ( <TokenLogo src="https://assets.coingecko.com/coins/images/279/large/ethereum.png" symbol="ETH" name="Ethereum" showTooltip /> )}Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | null | - | Token image URL |
symbol | string | null | - | Token symbol, used for alt text and fallback |
name | string | null | - | Token name, used for alt text and fallback |
address | string | null | - | Token contract address, used for icon inference and as a fallback label |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | Visual size |
fallback | ReactNode | Symbol/name/address fallback | Custom fallback content |
chainId | number | null | - | EVM chain id, used with address to infer an icon |
isNative | boolean | false | Use the native-currency icon instead of the token contract icon |
showTooltip | boolean | false | Show an animated tooltip |
tooltipContent | ReactNode | Name, symbol, then address | Tooltip content |
className | string | - | Applied to the root wrapper |
imageClassName | string | - | Applied to the image |
fallbackClassName | string | - | Applied to the fallback |
