Web3 Icons

Depending on your project requirements, choose one of the following packages:

• @web3icons/react: Provides React components with full TypeScript support.
• @web3icons/core: Provides framework-agnostic SVG files.
• @web3icons/common: Provides TypeScript types and metadata.

A robust token list component should incorporate the following features:

1. Dynamic Icons: Use @web3icons/react/dynamic to render icons based on incoming token data (e.g., symbol or contract address).
2. Search & Filtering: Implement search functionality by token symbol and name, using memoization to keep filtering performant.
3. Smart Sorting: Order tokens by popularity first, followed by balance or alphabetical order.
4. Network Context: Include network badges to provide multi-chain context for each token.
5. Performance: Use virtualization (e.g., react-window) for lists containing more than ~100 items to maintain smooth scrolling.
6. Accessibility: Adhere to ARIA patterns (combobox/listbox) and keyboard navigation support.

Web3 Icons support three distinct visual variants to match different UI requirements:

• mono: Monochromatic icons that inherit the current text color.
• branded: Icons using their official brand colors.
• background: Icons rendered with circular backgrounds.

Icons are organized by type, variant, and symbol. When accessing files directly or via imports, follow these naming rules:

Asset Types and Variants

• Types: tokens, networks, wallets, exchanges
• Variants: branded, mono, background

Naming Rules by Type

• Tokens: Ticker in uppercase (e.g., ETH, BTC, GRT).
• Networks: kebab-case (e.g., ethereum, binance-smart-chain).
• Wallets: kebab-case (e.g., metamask, coinbase-wallet).
• Exchanges: kebab-case (e.g., coinbase, uniswap).

Example File Paths

• svgs/tokens/branded/BTC.svg
• svgs/networks/mono/ethereum.svg
• svgs/wallets/branded/metamask.svg
• svgs/exchanges/mono/bybit.svg

The example projects demonstrate two distinct ways to consume icons, which affects bundle size and performance:

1. Static Imports (/): Uses standard static imports. This approach is tree-shakable, meaning only the icons explicitly imported are included in your final bundle.
2. Dynamic Imports (/dynamic): Uses dynamic imports for runtime lookup, allowing for more flexible icon loading at the cost of different bundling characteristics.

Dynamic icon components in @web3icons/react load icons at runtime based on props. They are ideal for user-driven interfaces where icons are not known at build time (e.g., displaying a user's wallet holdings or network selection).

Warning: Dynamic components are client-only and include all icons in the bundle. For optimal bundle size, prefer individual imports (e.g., TokenBTC) when the icons are known at build time.

To optimize your bundle size, you should use Individual Icon Components imported from the main entry point. These are tree-shakable, meaning only the icons you explicitly import will be included in your final bundle.

Warning: Dynamic components (like <TokenIcon />) are NOT tree-shakable. They load icons on-demand at runtime using dynamic imports, which can increase bundle size and are not compatible with Server Components.

// ✅ Static components (server-safe, tree-shakable)
import { TokenBTC, NetworkEthereum } from '@web3icons/react'

// ❌ Dynamic components (client-side only, NOT tree-shakable)
import { TokenIcon, NetworkIcon } from '@web3icons/react/dynamic'

For cryptocurrency applications, SVG is superior to PNG for several reasons:

• File Size: Optimized SVGs are significantly smaller (avg ~2.1 KB) compared to standard PNGs (avg ~8.4 KB) or retina PNGs (avg ~18.7 KB).
• Scalability: SVGs are vector-based and render perfectly at any size (from 16px to 1600px+), whereas PNGs become blurry when scaled up.
• Dark Mode & Styling: SVGs are part of the DOM and can be styled directly with CSS. You can change colors dynamically using the color prop or CSS color property, which is not possible with flat PNG raster images.
• Performance: SVGs can be inlined directly into your JSX/HTML, eliminating extra HTTP requests. web3icons React components use this approach.
• Accessibility: SVGs allow for rich accessibility via <title>, <desc>, aria-label, and role attributes.

To minimize bundle size, use individual static imports for icons. This allows your bundler to tree-shake unused icons, resulting in a bundle impact of approximately 1-2KB gzipped per icon.

Avoid dynamic lookups from a central Icons object (e.g., Icons[iconName]), as this prevents tree-shaking and forces the inclusion of all icons in your bundle (~2MB+ gzipped).

// Good - only BTC and ETH icons included
import { TokenBTC, TokenETH } from '@web3icons/react';

// Bad - includes ALL icons
import { Icons } from '@web3icons/react';
const iconName = 'TokenETH';
const Icon = Icons[iconName]; // Dynamic lookup prevents tree-shaking

Icons within SvgCollections are accessed using specific key patterns based on their type. Use these patterns to construct keys for dynamic lookups.

Key Patterns

• Tokens: {variant}{SYMBOL} (e.g., brandedBTC, monoETH)
• Networks: {variant}{PascalCase} (e.g., brandedEthereum, monoPolygon)
• Wallets: {variant}{PascalCase} (e.g., brandedMetamask, monoRainbow)
• Exchanges: {variant}{PascalCase} (e.g., brandedUniswap, monoBinance)

Available Variants

• branded: Official brand colors (Available for all types)
• mono: Monochromatic, single color (Available for all types)
• background: Circular background (Available for tokens only)