@nautilus/crypto-icons

Network-agnostic crypto icon library for React with composable overlay badges. Display token, network, protocol, and wallet icons across multiple ecosystems using a unified, type-safe API.

Installation

npm install @nautilus/crypto-icons

Peer dependencies:

npm install react react-dom

Import the stylesheet once in your app entry:

import "@nautilus/crypto-icons/style.css";

Basic usage

import { CryptoIcon, NetworkIcon, ProtocolIcon } from "@nautilus/crypto-icons";
import "@nautilus/crypto-icons/style.css";

function App() {
  return (
    <>
      {/* Symbol + network (default network badge bottom-right) */}
      <CryptoIcon symbol="USDC" network="base" />

      {/* Algorand asset ID */}
      <CryptoIcon assetId={31566704} network="algorand" />

      {/* Voi contract ID */}
      <CryptoIcon contractId={390001} network="voi" />

      {/* EVM contract address */}
      <CryptoIcon
        address="0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        network="ethereum"
      />

      <NetworkIcon network="algorand" />
      <ProtocolIcon protocol="dorkfi" />
    </>
  );
}

Badge presets

By default, CryptoIcon renders the associated network badge on the bottom-right corner.

<CryptoIcon symbol="USDC" network="base" />
<CryptoIcon symbol="USDC" network="base" badgePreset="network-top-right" />
<CryptoIcon symbol="VOI" network="voi" badgePreset="none" />

Available presets:

Preset	Description
network-bottom-right	Default — network badge bottom-right
network-top-right	Network badge top-right
network-bottom-left	Network badge bottom-left
network-top-left	Network badge top-left
none	No badges
custom	Use only the badges prop

Custom badges

Configure up to four corner badges with full control:

<CryptoIcon
  symbol="USDC"
  network="base"
  badgePreset="custom"
  badges={{
    topLeft: { type: "network", value: "ethereum" },
    topRight: { type: "protocol", value: "dorkfi" },
    bottomLeft: { type: "wallet", value: "pera" },
    bottomRight: { type: "network", value: "base" },
  }}
/>

Badge types: network, token, protocol, wallet, custom.

Custom badge example:

<CryptoIcon
  symbol="ETH"
  badges={{
    topRight: {
      type: "custom",
      label: "L2",
      background: "#6366f1",
      border: "#ffffff",
      rounded: true,
    },
  }}
/>

Token pairs and stacks

import { TokenPairIcon, IconStack } from "@nautilus/crypto-icons";

<TokenPairIcon tokenA="ALGO" tokenB="USDC" />
<IconStack icons={["ETH", "USDC", "BASE"]} size="lg" />

Registry extension

Extend the built-in registries at runtime:

import {
  registerToken,
  registerNetwork,
  registerProtocol,
  registerWallet,
  tokens,
  networks,
} from "@nautilus/crypto-icons";

registerToken({
  id: "my-token-arbitrum",
  symbol: "MYT",
  name: "My Token",
  network: "arbitrum",
  address: "0xabc...",
  icon: "<svg>...</svg>",
});

registerNetwork({
  id: "custom-chain",
  name: "Custom Chain",
  network: "ethereum", // extend NetworkId in your app if needed
  icon: "<svg>...</svg>",
});

console.log(tokens.length, networks.length);

Resolution priority:

1. Exact network + identifier (assetId, contractId, address, mint)
2. Exact network + symbol
3. Global symbol match
4. Alias match
5. Unknown fallback

TypeScript

import type {
  AssetRef,
  NetworkId,
  IconBadgeConfig,
  IconBadges,
  ResolvedIcon,
} from "@nautilus/crypto-icons";
import { resolveTokenIcon } from "@nautilus/crypto-icons";

const ref: AssetRef = {
  network: "algorand",
  assetId: 31566704,
  symbol: "USDC",
};

const resolved: ResolvedIcon = resolveTokenIcon(ref);

const badges: IconBadges = {
  bottomRight: { type: "network", value: "base" satisfies NetworkId },
};

Theming

Icons use CSS custom properties for sizing and badge borders:

.my-icon {
  --nci-size: 32px;
  --nci-bg: #0f172a;
  --nci-border-color: #0f172a;
}

<CryptoIcon
  symbol="USDC"
  network="base"
  size="lg"
  className="my-icon"
  rounded
/>

Size presets: sm (16px), md (24px), lg (32px), xl (48px), or any pixel value.

Fallback modes: generic (default), initials, none.

Development

npm install
npm run dev      # Vite dev playground
npm run build    # ESM + CJS + types + CSS
npm run typecheck
npm run lint

License

MIT